{
  "openapi": "3.1.0",
  "info": {
    "title": "Novi Forecasts API",
    "version": "1.103.0",
    "summary": "Wells, subsurface grids and production forecasts for drawn horizontal wells.",
    "description": "Forecast oil, gas and water from horizontal wells before they are drilled, in the basins GET /model-sets lists.\n\nThe API serves the same data and models as the Forecasts app: existing wells with their production, spacing\nneighbors and spacing features; subsurface grids for each formation; and forecasts for wells you design. A drawn well\nruns through spacing (its neighbors), spacing features (depletion and spacing at every ip_day),\nsubsurface interpolation and the oil, gas and water models, and comes back with cumulative volumes by ip_day.\n\nConventions:\n\n- JSON in and out, with snake_case names. POST /areas, POST /area-sets, POST /inventories/read, POST /pads/read,\n  POST /completion-designs/read and POST /forecast-sources[/read] also take a multipart file upload.\n- Units are in field names or descriptions: feet, bbl, mcf, bbl/ft and lb/ft. `GET /conventions` lists them with\n  the BOE ratio (6 mcf per bbl) and the P-level convention.\n- Points are `[lng, lat]` arrays in request bodies and `\"lng,lat\"` strings in query parameters (WGS 84 degrees).\n- Volumes are cumulative by `ip_day` (days since first production); rates are daily averages.\n- Every response carries `X-Request-Id` (send your own to correlate). Errors share one envelope,\n  `{\"error\": {\"code\", \"message\", \"details\"}, \"request_id\"}`; `details.field` names the input at fault.\n  - `invalid_argument`: 400, 401, 403, 405, 413 and 416. 405 answers a method\n    the path lacks, with an `Allow` header and `details.allow`.\n  - `not_found`: 404 and 410. `conflict`: 409, and 429 for POST /plans past one caller's unfinished plans, with\n    `Retry-After`. `internal`: 500, and 502 when a model worker failed. `unavailable`: 503.\n- Large lists page with `limit` and an opaque `cursor`; pass `next_cursor` back until it is null.\n- Dataset reads, economics decks and the changelog carry an `ETag` and answer `If-None-Match` with 304; done or\n  failed plan reads carry one with `Cache-Control: private, no-cache`. Responses over 1 KB are gzipped when you\n  send `Accept-Encoding: gzip`. Browsers on sites outside Novi's domain are refused at the CORS preflight.\n- Forecasts of up to 50 wells run in the request (`POST /forecasts`), or as a job with `async: true`.\n- Plans of up to GET /dataset `limits.plan_wells` forecasts (10,000 by default) and **exports** of a done plan's\n  tables run as jobs: `POST /plans` or `POST /exports` answers 202; GET the job with `wait=25` until\n  `status` is `done`, or name a `callback_url` on a server that allows callbacks.\n- `POST /plans`, `POST /exports` and `POST /forecast-sources` take an `Idempotency-Key` header: a retry with\n  the same key and body returns what the first request made instead of starting again.\n- Completions are **designs**: a request's `designs` (fluid and proppant per ft) apply to every well, and each well\n  comes back with one forecast per design, in design order. With one design, a\n  well, pad, layout or scenario can set its own (see WellInput `fluid_bbl_per_ft`).\n  - Spacing and its features don't depend on completions, so every design shares them.\n- **Explanations** are the models' own: SHAP per ip_day and the training wells the forecast leans on, with options\n  for the model's analog wells. Ask with `explain: true` on POST /forecasts, or per plan well and design. An analog\n  spread is a spread of analog wells, not the model's uncertainty.\n- **EUR** (estimated ultimate recovery) is opt-in with `eur: true`: Novi's type-curve decline fit extends the\n  3-year forecast, as Novi's earlier Forecast Engine runs it for planned wells. It is not a model output. POST\n  /declines fits curves you already have.\n- **Economics** are the Pad Optimizer's simulated half-cycle economics (IRR, payback and NPV), priced on the server\n  by POST /economics under the set's illustrative deck (GET /economics/deck), not a Novi default.\n- **P10/P90 bands** are opt-in with `bands: true`: a low (`p10`) and a high (`p90`) cumulative curve per stream\n  from Novi's predrill bands. Percentiles follow Novi's convention: p10 is the low curve.\n- **TIL dates** schedule wells: a well's own `til_date`, else its pad's or layout's, else its scenario's, else the\n  request's, is its first day of production; blank is today. They order parents and children in spacing and set\n  the dates the spacing features use.\n- **Depletion chain**: a dated plan feeds each planned well's P50 production to the later plan wells it is a parent\n  of, where the set's models read neighbors' production (GET /dataset `depletion_chain`).\n- **Model sets**: `GET /model-sets` lists the datasets with their models this server can serve. Send `model_set`\n  on any dataset-scoped operation to use one; without it, the set GET /model-sets names as `default` answers.\n  - Plans and exports made under a set keep to it, so their later calls need no `model_set`. Each set keeps its own\n    plans, exports (with their queue and limits) and forecast cache; plan chunks share one queue across sets."
  },
  "servers": [
    {
      "url": "https://{company}.novilabs.io/forecasts/api/v1",
      "description": "Your company's Novi host",
      "variables": {
        "company": {
          "default": "your-company",
          "description": "The subdomain of your company's Novi host"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Service",
      "description": "Health, the dataset behind the API, its units and conventions, the field dictionary, what changed in each release and this document."
    },
    {
      "name": "Wells",
      "description": "Existing wells: attributes, production, spacing neighbors and spacing features."
    },
    {
      "name": "Subsurface",
      "description": "Formation grids (structure, thickness, BVI) and interpolated values along a well path."
    },
    {
      "name": "Design",
      "description": "Inputs for drawn wells: completion defaults and designs, TVD estimates, filled layouts, gun barrels, pads, well inventories, areas and area sets read from boundary files, and the Texas land survey grid."
    },
    {
      "name": "Forecasts",
      "description": "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."
    },
    {
      "name": "Economics",
      "description": "The Pad Optimizer's simulated economics: the deck it prices with, and IRR, payback and NPV at the deck's discount rate for scenarios of forecast wells."
    },
    {
      "name": "Plans",
      "description": "Development plans of up to GET /dataset `limits.plan_wells` forecasts (wells × designs; 10,000 by default), run as background jobs, with explanations per well."
    },
    {
      "name": "Saved documents",
      "description": "Tenant-scoped filter sets, completion designs, type curves, views, settings, assumption sets, column mappings and plan views."
    },
    {
      "name": "Forecast sources",
      "description": "Booked forecasts read from Val Nav, Novi, ComboCurve, Mosaic and ARIES files, kept per tenant, private to their creator by default, optionally linked to a plan."
    },
    {
      "name": "Exports",
      "description": "A done plan's tables as one zip, written by a queued job: presets or your own tables and columns, status and progress, and a download that resumes."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "tags": [
          "Service"
        ],
        "summary": "Check service health",
        "description": "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.\n\n**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.\n\n**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": {
            "description": "Service health.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                },
                "example": {
                  "status": "ok",
                  "version": "1.28.0",
                  "sample_data": true,
                  "dataset": "SAMPLE_Midland_Sep2026",
                  "uptime_s": 5321,
                  "host": {
                    "cpus": 4,
                    "cpu_model": "Intel(R) Xeon(R) Platinum 8375C CPU @ 2.90GHz"
                  },
                  "checks": {
                    "database": "ok",
                    "subsurface": "ready",
                    "spacing_and_features": "ok",
                    "workers": {
                      "spacing": "ready",
                      "calc": "ready",
                      "forecast": "ready"
                    }
                  },
                  "app_version": "0.36",
                  "clients": {
                    "mcpb": {
                      "version": "0.36.0",
                      "min_supported": "0.35.0",
                      "download": "/downloads/novi-forecasts.mcpb",
                      "setup": "/#/api"
                    },
                    "skill": {
                      "version": "0.36",
                      "download": "/downloads/novi-forecasts-skill.zip"
                    }
                  },
                  "web": {
                    "status": "ok",
                    "sha": "3f2a9c41d07e5b8a6c1f94e2d3b7a05c8e6f1d29",
                    "version": "1.0",
                    "requires_api": "1.26.0",
                    "checked_at": "2026-10-23T14:02:11.408Z",
                    "error": null
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        }
      }
    },
    "/dataset": {
      "get": {
        "operationId": "getDataset",
        "tags": [
          "Service"
        ],
        "summary": "Describe the dataset",
        "description": "The dataset's name, build and as-of date, basin, well count and extent; its forecast models per stream, with their features and ip_days; the request limits; and which streams have EUR and P10/P90 bands.\n\n**Options.** `include` adds the oil or gas stream with the larger share of first-12-month BOE, or the count of wells without a location, which GET /wells leaves out.",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "description": "`primary_stream` adds the stream, oil or gas, with the larger share of the dataset's first-12-month BOE, and `unlocated_well_count` the number of wells in `well_count` without a location (no longitude), which GET /wells and the map leave out; send either or both, comma-separated or repeated, each once, and any other value is a 400 with details.field include.",
            "schema": {
              "type": "string",
              "enum": [
                "primary_stream",
                "unlocated_well_count",
                "primary_stream,unlocated_well_count",
                "unlocated_well_count,primary_stream"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The dataset.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dataset"
                },
                "examples": {
                  "all": {
                    "summary": "Dataset",
                    "value": {
                      "name": "SAMPLE_Midland_Sep2026",
                      "build": "S20260930",
                      "sample_data": true,
                      "basin": "Midland",
                      "region": "Permian",
                      "well_count": 18000,
                      "formation_count": 8,
                      "as_of": "2026-09-30",
                      "first_production": "2012-02-24",
                      "bbox": [
                        -102.53241,
                        31.15189,
                        -101.22079,
                        32.48628
                      ],
                      "models": [
                        {
                          "stream": "oil",
                          "model_num": "M20260930-sample-O-d1",
                          "target": "novi_oil",
                          "features": [
                            "novi_lateral_length",
                            "novi_tvd",
                            "novi_formation",
                            "novi_calc_fluid_per_length",
                            "novi_calc_proppant_per_length",
                            "novi_spacing_lateralcloser_mintangent",
                            "novi_spacing_lateralfarther_mintangent",
                            "novi_spacing_staggercloser_mintangent",
                            "novi_spacing_staggerfarther_mintangent",
                            "novi_spacing_parent_mintangent",
                            "novi_spacing_parent_daysonline",
                            "novi_bvi_avg",
                            "novi_bvi_ofnet"
                          ],
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ]
                        },
                        {
                          "stream": "gas",
                          "model_num": "M20260930-sample-G-d1",
                          "target": "novi_gas",
                          "features": [
                            "novi_lateral_length",
                            "novi_tvd",
                            "novi_formation",
                            "novi_calc_fluid_per_length",
                            "novi_calc_proppant_per_length",
                            "novi_spacing_lateralcloser_mintangent",
                            "novi_spacing_lateralfarther_mintangent",
                            "novi_spacing_staggercloser_mintangent",
                            "novi_spacing_staggerfarther_mintangent",
                            "novi_spacing_parent_mintangent",
                            "novi_spacing_parent_daysonline",
                            "novi_bvi_avg",
                            "novi_bvi_ofnet"
                          ],
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ]
                        },
                        {
                          "stream": "water",
                          "model_num": "M20260930-sample-W-d1",
                          "target": "novi_water",
                          "features": [
                            "novi_lateral_length",
                            "novi_tvd",
                            "novi_formation",
                            "novi_calc_fluid_per_length",
                            "novi_calc_proppant_per_length",
                            "novi_spacing_lateralcloser_mintangent",
                            "novi_spacing_lateralfarther_mintangent",
                            "novi_spacing_staggercloser_mintangent",
                            "novi_spacing_staggerfarther_mintangent",
                            "novi_spacing_parent_mintangent",
                            "novi_spacing_parent_daysonline",
                            "novi_bvi_avg",
                            "novi_bvi_ofnet"
                          ],
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ]
                        }
                      ],
                      "ip_days": [
                        30,
                        60,
                        90,
                        1080
                      ],
                      "spacing": {
                        "search_radius_ft": 10000
                      },
                      "subsurface": {
                        "method": "linear",
                        "grids": 40,
                        "distance_from_grids": 3,
                        "distance_from_grids_units": "mi"
                      },
                      "limits": {
                        "forecast_wells": 50,
                        "plan_wells": 10000,
                        "plan_unfinished_forecasts": 40000
                      },
                      "eur": {
                        "available": true,
                        "method": "Novi's decline fit (modified Arps)",
                        "defaults": {
                          "eur_years": 50,
                          "terminal_decline": 0.06,
                          "b_min": 0.5,
                          "b_max": 2.5
                        },
                        "bounds": {
                          "eur_years": {
                            "min": 10,
                            "max": 50
                          },
                          "terminal_decline": {
                            "min": 0.01,
                            "max": 0.2
                          },
                          "b_min": {
                            "min": 0,
                            "max": 2.5
                          },
                          "b_max": {
                            "min": 0,
                            "max": 2.5
                          }
                        },
                        "streams": [
                          "oil",
                          "gas"
                        ],
                        "versions": null
                      },
                      "bands": {
                        "available": true,
                        "method": "Novi's predrill bands (split conformal)",
                        "percentiles": [
                          10,
                          90
                        ],
                        "streams": [
                          "oil",
                          "gas",
                          "water"
                        ],
                        "reason": null
                      },
                      "depletion_chain": {
                        "available": false,
                        "features": [],
                        "neighbor_production": "history"
                      }
                    }
                  },
                  "primary_stream": {
                    "summary": "include=primary_stream",
                    "value": {
                      "name": "SAMPLE_Midland_Sep2026",
                      "build": "S20260930",
                      "sample_data": true,
                      "basin": "Midland",
                      "region": "Permian",
                      "well_count": 18000,
                      "formation_count": 8,
                      "as_of": "2026-09-30",
                      "first_production": "2012-02-24",
                      "bbox": [
                        -102.53241,
                        31.15189,
                        -101.22079,
                        32.48628
                      ],
                      "models": [
                        {
                          "stream": "oil",
                          "model_num": "M20260930-sample-O-d1",
                          "target": "novi_oil",
                          "features": [
                            "novi_lateral_length",
                            "novi_tvd",
                            "novi_formation",
                            "novi_calc_fluid_per_length",
                            "novi_calc_proppant_per_length",
                            "novi_spacing_lateralcloser_mintangent",
                            "novi_spacing_lateralfarther_mintangent",
                            "novi_spacing_staggercloser_mintangent",
                            "novi_spacing_staggerfarther_mintangent",
                            "novi_spacing_parent_mintangent",
                            "novi_spacing_parent_daysonline",
                            "novi_bvi_avg",
                            "novi_bvi_ofnet"
                          ],
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ]
                        },
                        {
                          "stream": "gas",
                          "model_num": "M20260930-sample-G-d1",
                          "target": "novi_gas",
                          "features": [
                            "novi_lateral_length",
                            "novi_tvd",
                            "novi_formation",
                            "novi_calc_fluid_per_length",
                            "novi_calc_proppant_per_length",
                            "novi_spacing_lateralcloser_mintangent",
                            "novi_spacing_lateralfarther_mintangent",
                            "novi_spacing_staggercloser_mintangent",
                            "novi_spacing_staggerfarther_mintangent",
                            "novi_spacing_parent_mintangent",
                            "novi_spacing_parent_daysonline",
                            "novi_bvi_avg",
                            "novi_bvi_ofnet"
                          ],
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ]
                        },
                        {
                          "stream": "water",
                          "model_num": "M20260930-sample-W-d1",
                          "target": "novi_water",
                          "features": [
                            "novi_lateral_length",
                            "novi_tvd",
                            "novi_formation",
                            "novi_calc_fluid_per_length",
                            "novi_calc_proppant_per_length",
                            "novi_spacing_lateralcloser_mintangent",
                            "novi_spacing_lateralfarther_mintangent",
                            "novi_spacing_staggercloser_mintangent",
                            "novi_spacing_staggerfarther_mintangent",
                            "novi_spacing_parent_mintangent",
                            "novi_spacing_parent_daysonline",
                            "novi_bvi_avg",
                            "novi_bvi_ofnet"
                          ],
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ]
                        }
                      ],
                      "ip_days": [
                        30,
                        60,
                        90,
                        1080
                      ],
                      "spacing": {
                        "search_radius_ft": 10000
                      },
                      "subsurface": {
                        "method": "linear",
                        "grids": 40,
                        "distance_from_grids": 3,
                        "distance_from_grids_units": "mi"
                      },
                      "limits": {
                        "forecast_wells": 50,
                        "plan_wells": 10000,
                        "plan_unfinished_forecasts": 40000
                      },
                      "eur": {
                        "available": true,
                        "method": "Novi's decline fit (modified Arps)",
                        "defaults": {
                          "eur_years": 50,
                          "terminal_decline": 0.06,
                          "b_min": 0.5,
                          "b_max": 2.5
                        },
                        "bounds": {
                          "eur_years": {
                            "min": 10,
                            "max": 50
                          },
                          "terminal_decline": {
                            "min": 0.01,
                            "max": 0.2
                          },
                          "b_min": {
                            "min": 0,
                            "max": 2.5
                          },
                          "b_max": {
                            "min": 0,
                            "max": 2.5
                          }
                        },
                        "streams": [
                          "oil",
                          "gas"
                        ],
                        "versions": null
                      },
                      "bands": {
                        "available": true,
                        "method": "Novi's predrill bands (split conformal)",
                        "percentiles": [
                          10,
                          90
                        ],
                        "streams": [
                          "oil",
                          "gas",
                          "water"
                        ],
                        "reason": null
                      },
                      "depletion_chain": {
                        "available": false,
                        "features": [],
                        "neighbor_production": "history"
                      },
                      "primary_stream": "oil"
                    }
                  },
                  "unlocated_well_count": {
                    "summary": "include=unlocated_well_count",
                    "value": {
                      "name": "SAMPLE_Midland_Sep2026",
                      "build": "S20260930",
                      "sample_data": true,
                      "basin": "Midland",
                      "region": "Permian",
                      "well_count": 18000,
                      "formation_count": 8,
                      "as_of": "2026-09-30",
                      "first_production": "2012-02-24",
                      "bbox": [
                        -102.53241,
                        31.15189,
                        -101.22079,
                        32.48628
                      ],
                      "models": [
                        {
                          "stream": "oil",
                          "model_num": "M20260930-sample-O-d1",
                          "target": "novi_oil",
                          "features": [
                            "novi_lateral_length",
                            "novi_tvd",
                            "novi_formation",
                            "novi_calc_fluid_per_length",
                            "novi_calc_proppant_per_length",
                            "novi_spacing_lateralcloser_mintangent",
                            "novi_spacing_lateralfarther_mintangent",
                            "novi_spacing_staggercloser_mintangent",
                            "novi_spacing_staggerfarther_mintangent",
                            "novi_spacing_parent_mintangent",
                            "novi_spacing_parent_daysonline",
                            "novi_bvi_avg",
                            "novi_bvi_ofnet"
                          ],
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ]
                        },
                        {
                          "stream": "gas",
                          "model_num": "M20260930-sample-G-d1",
                          "target": "novi_gas",
                          "features": [
                            "novi_lateral_length",
                            "novi_tvd",
                            "novi_formation",
                            "novi_calc_fluid_per_length",
                            "novi_calc_proppant_per_length",
                            "novi_spacing_lateralcloser_mintangent",
                            "novi_spacing_lateralfarther_mintangent",
                            "novi_spacing_staggercloser_mintangent",
                            "novi_spacing_staggerfarther_mintangent",
                            "novi_spacing_parent_mintangent",
                            "novi_spacing_parent_daysonline",
                            "novi_bvi_avg",
                            "novi_bvi_ofnet"
                          ],
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ]
                        },
                        {
                          "stream": "water",
                          "model_num": "M20260930-sample-W-d1",
                          "target": "novi_water",
                          "features": [
                            "novi_lateral_length",
                            "novi_tvd",
                            "novi_formation",
                            "novi_calc_fluid_per_length",
                            "novi_calc_proppant_per_length",
                            "novi_spacing_lateralcloser_mintangent",
                            "novi_spacing_lateralfarther_mintangent",
                            "novi_spacing_staggercloser_mintangent",
                            "novi_spacing_staggerfarther_mintangent",
                            "novi_spacing_parent_mintangent",
                            "novi_spacing_parent_daysonline",
                            "novi_bvi_avg",
                            "novi_bvi_ofnet"
                          ],
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ]
                        }
                      ],
                      "ip_days": [
                        30,
                        60,
                        90,
                        1080
                      ],
                      "spacing": {
                        "search_radius_ft": 10000
                      },
                      "subsurface": {
                        "method": "linear",
                        "grids": 40,
                        "distance_from_grids": 3,
                        "distance_from_grids_units": "mi"
                      },
                      "limits": {
                        "forecast_wells": 50,
                        "plan_wells": 10000,
                        "plan_unfinished_forecasts": 40000
                      },
                      "eur": {
                        "available": true,
                        "method": "Novi's decline fit (modified Arps)",
                        "defaults": {
                          "eur_years": 50,
                          "terminal_decline": 0.06,
                          "b_min": 0.5,
                          "b_max": 2.5
                        },
                        "bounds": {
                          "eur_years": {
                            "min": 10,
                            "max": 50
                          },
                          "terminal_decline": {
                            "min": 0.01,
                            "max": 0.2
                          },
                          "b_min": {
                            "min": 0,
                            "max": 2.5
                          },
                          "b_max": {
                            "min": 0,
                            "max": 2.5
                          }
                        },
                        "streams": [
                          "oil",
                          "gas"
                        ],
                        "versions": null
                      },
                      "bands": {
                        "available": true,
                        "method": "Novi's predrill bands (split conformal)",
                        "percentiles": [
                          10,
                          90
                        ],
                        "streams": [
                          "oil",
                          "gas",
                          "water"
                        ],
                        "reason": null
                      },
                      "depletion_chain": {
                        "available": false,
                        "features": [],
                        "neighbor_production": "history"
                      },
                      "unlocated_well_count": 0
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/formations": {
      "get": {
        "operationId": "listFormations",
        "tags": [
          "Service"
        ],
        "summary": "List formations",
        "description": "Formations, top to bottom, with well counts and the subsurface grid for each rock property. Model evaluation, baselines and plan stats group formations in this order.\n\n**Order.** By the median TVD of their wells, then name (those without one last); formations in the set's rock column (the one POST /gun-barrels draws) are then re-ordered by it among the places they hold.\n\n- Others keep their place; formations on one surface keep their median TVD order.\n- A column formation without a median TVD follows the one before it in the column (or, first, precedes the one after it); if none has one, nothing moves.\n- Without a column (no structure grids, or it can't be built), the order is by median TVD; if a set with structure grids can't build it, the answer is Cache-Control no-store and the next call tries again.\n\n**Targets.** include=target marks the formations to plan or draw a well in.",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "description": "`target` adds `target` to each formation: true for one with wells and Novi subsurface grids that the served models were trained in (the Formation schema states the rule), a zone to plan or draw a well in. Any other value is a 400 with details.field include.",
            "schema": {
              "type": "string",
              "enum": [
                "target"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "Formations.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormationList"
                },
                "examples": {
                  "all": {
                    "summary": "Formations",
                    "value": {
                      "formations": [
                        {
                          "name": "MIDDLE SPRABERRY",
                          "label": "Middle Spraberry",
                          "well_count": 1594,
                          "median_tvd_ft": 7534,
                          "median_lateral_ft": 9920,
                          "grids": {
                            "novi_structuraldepth": "novi_structuraldepth_middle_spraberry",
                            "novi_thickness_avg": "novi_thickness_avg_middle_spraberry",
                            "novi_thickness_ofnet": "novi_thickness_ofnet_middle_spraberry",
                            "novi_bvi_avg": "novi_bvi_avg_middle_spraberry",
                            "novi_bvi_ofnet": "novi_bvi_ofnet_middle_spraberry"
                          },
                          "has_grids": true
                        },
                        {
                          "name": "JO MILL",
                          "label": "Jo Mill",
                          "well_count": 1015,
                          "median_tvd_ft": 7960,
                          "median_lateral_ft": 9760,
                          "grids": {
                            "novi_structuraldepth": "novi_structuraldepth_jo_mill",
                            "novi_thickness_avg": "novi_thickness_avg_jo_mill",
                            "novi_thickness_ofnet": "novi_thickness_ofnet_jo_mill",
                            "novi_bvi_avg": "novi_bvi_avg_jo_mill",
                            "novi_bvi_ofnet": "novi_bvi_ofnet_jo_mill"
                          },
                          "has_grids": true
                        }
                      ]
                    }
                  },
                  "target": {
                    "summary": "include=target",
                    "value": {
                      "formations": [
                        {
                          "name": "MIDDLE SPRABERRY",
                          "label": "Middle Spraberry",
                          "well_count": 1594,
                          "median_tvd_ft": 7534,
                          "median_lateral_ft": 9920,
                          "grids": {
                            "novi_structuraldepth": "novi_structuraldepth_middle_spraberry",
                            "novi_thickness_avg": "novi_thickness_avg_middle_spraberry",
                            "novi_thickness_ofnet": "novi_thickness_ofnet_middle_spraberry",
                            "novi_bvi_avg": "novi_bvi_avg_middle_spraberry",
                            "novi_bvi_ofnet": "novi_bvi_ofnet_middle_spraberry"
                          },
                          "has_grids": true,
                          "target": true
                        },
                        {
                          "name": "JO MILL",
                          "label": "Jo Mill",
                          "well_count": 1015,
                          "median_tvd_ft": 7960,
                          "median_lateral_ft": 9760,
                          "grids": {
                            "novi_structuraldepth": "novi_structuraldepth_jo_mill",
                            "novi_thickness_avg": "novi_thickness_avg_jo_mill",
                            "novi_thickness_ofnet": "novi_thickness_ofnet_jo_mill",
                            "novi_bvi_avg": "novi_bvi_avg_jo_mill",
                            "novi_bvi_ofnet": "novi_bvi_ofnet_jo_mill"
                          },
                          "has_grids": true,
                          "target": true
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/wells": {
      "get": {
        "operationId": "listWells",
        "tags": [
          "Wells"
        ],
        "summary": "List wells",
        "description": "Existing wells for a map: every matching well as parallel arrays (`format=columns`, the default), or a page of GeoJSON Points at each lateral's midpoint (`format=geojson`).\n\n**Formats.** `format=columns` includes names, operators and first year: about 0.6 MB gzipped for the whole basin. Both formats page with `limit` and `cursor`. `fields` keeps only the fields you name, and adds header fields and derived ones: per-ft completions, and 12-month BOE, oil and gas per 1,000 ft of lateral.\n\n**Filters.** Filters combine. To find wells by name, key or operator without downloading the basin, send `q` or `operator` with `format=geojson` and a small `limit`. `near` keeps the wells within `radius_mi`, nearest first, each with its `distance_mi`. `county` and `operators` match exact names, `keys` wellbore keys; `sort` and `order` order the wells. GET /wells/facets counts wells by value, for pickers and range sliders.\n\n**Ranges.** `<field>_min` and `<field>_max` are inclusive and compare the value as a response shows it, rounded; a well without the value never matches. Numbers are digits with an optional decimal, as 9000.5; dates are YYYY-MM-DD. A `_min` above its `_max` is a 400; a range on a field without one is ignored, as any unknown parameter is.\n\n**Applied.** `applied` echoes how the server read `sort`, `order`, `county`, `operators`, the ranges and columns paging; absent when none is sent.",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "description": "Response layout.",
            "schema": {
              "type": "string",
              "enum": [
                "columns",
                "geojson"
              ],
              "default": "columns"
            }
          },
          {
            "name": "formation",
            "in": "query",
            "description": "Only these formations: one name or a comma-separated list, case-insensitive, as `WOLFCAMP A,WOLFCAMP B`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bbox",
            "in": "query",
            "description": "Only wells whose lateral midpoint is inside `west,south,east,north` (degrees), as `-102.05,31.9,-101.85,32.05`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Only wells whose name or wellbore key contains this text, ignoring case: `woodard trust` matches WOODARD TRUST 32-44 2WB. Leading and trailing spaces are ignored; up to 100 characters (400 past it).",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "operator",
            "in": "query",
            "description": "Only wells whose operator contains this text, ignoring case; up to 100 characters (400 past it).",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "near",
            "in": "query",
            "description": "Only wells within `radius_mi` of this point, nearest first, each with its `distance_mi`: `lng,lat` in WGS 84 degrees, longitude first as in `bbox`.\n\nDistance is great-circle miles to each lateral's midpoint; `distance_mi` rounds it to 0.01 (a column with `format=columns`, a property with `format=geojson`). Ties at the exact distance go by wellbore key, so `cursor` pages are stable. 400 unless it is two numbers within -180 to 180 and -90 to 90. Without it, wells come in wellbore key order.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "radius_mi",
            "in": "query",
            "description": "With `near` (400 without it): how far from it to look, in miles, a decimal greater than 0 and at most 100 written as digits (2 or 2.5); default 5.",
            "schema": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 100,
              "default": 5
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size: with format=geojson, 1 to 1,000 wells (default 100); with format=columns, 1 to 10,000 (100 when only `cursor` is sent), and the response adds `next_cursor`. Without `limit` or `cursor`, format=columns returns every matching well.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000,
              "default": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Page to read: `next_cursor` from the previous page, in either format.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Only these fields, comma-separated; absent or empty, every field. `wellbore_key` is always kept, and the response keeps its own key order.\n\nAllowed: the columns or properties listed below, and `distance_mi` with `near`.\n\nColumns, with format=columns: `wellbore_key`, `well_name`, `operator`, `formation`, `mid_lon`, `mid_lat`, `shl_lon`, `shl_lat`, `heel_lon`, `heel_lat`, `bhl_lon`, `bhl_lat`, `cum_boe_12`, `first_year`. Properties, with format=geojson: `wellbore_key`, `well_name`, `operator`, `formation`, `first_prod`, `lateral_length`, `tvd_td`, `cum_boe_12`, `shl_lon`, `shl_lat`, `heel_lon`, `heel_lat`, `bhl_lon`, `bhl_lat`. `distance_mi` without `near` is a 400.\n\nEither format also takes `basin`, `subbasin`, `state`, `county`, `lateral_length`, `tvd_td`, `lat`, `lon`, `first_prod`, `last_prod`, `cum_oil_12`, `cum_gas_12`, `cum_boe_12`, `cum_oil_life`, `cum_gas_life`, `cum_boe_life`, `total_proppant`, `total_fluid`, `stage_count`, `frac_date`, `til_date`, `first_year`, `fluid_bbl_per_ft`, `proppant_lb_per_ft`, `cum_boe_12_per_1000_ft`, `cum_oil_12_per_1000_ft`, `cum_gas_12_per_1000_ft`.\n\nThese are GET /wells/{key}'s header fields, `first_year`, per-ft completions, and 12-month BOE, oil (bbl) and gas (mcf) per 1,000 ft of lateral, after the default fields in that order.\n\nCoordinates are rounded to 5 decimals, volumes to whole units, per-ft values to 0.1, and dates are YYYY-MM-DD. `lat` and `lon` are the header's point; the map uses `mid_lon` and `mid_lat`.\n\nFor example `well_name,formation,cum_boe_12`. `count` and `format`, or a feature's `type`, `id` and `geometry` and the page's `next_cursor`, are always there.\n\nNames are top-level only (no dots), case-sensitive and never empty; one not allowed here is a 400 with the allowed names in `details.allowed`.",
            "x-allowed-fields": {
              "columns": [
                "wellbore_key",
                "well_name",
                "operator",
                "formation",
                "mid_lon",
                "mid_lat",
                "shl_lon",
                "shl_lat",
                "heel_lon",
                "heel_lat",
                "bhl_lon",
                "bhl_lat",
                "cum_boe_12",
                "first_year",
                "basin",
                "subbasin",
                "state",
                "county",
                "lateral_length",
                "tvd_td",
                "lat",
                "lon",
                "first_prod",
                "last_prod",
                "cum_oil_12",
                "cum_gas_12",
                "cum_oil_life",
                "cum_gas_life",
                "cum_boe_life",
                "total_proppant",
                "total_fluid",
                "stage_count",
                "frac_date",
                "til_date",
                "fluid_bbl_per_ft",
                "proppant_lb_per_ft",
                "cum_boe_12_per_1000_ft",
                "cum_oil_12_per_1000_ft",
                "cum_gas_12_per_1000_ft",
                "distance_mi"
              ],
              "geojson": [
                "wellbore_key",
                "well_name",
                "operator",
                "formation",
                "first_prod",
                "lateral_length",
                "tvd_td",
                "cum_boe_12",
                "shl_lon",
                "shl_lat",
                "heel_lon",
                "heel_lat",
                "bhl_lon",
                "bhl_lat",
                "basin",
                "subbasin",
                "state",
                "county",
                "lat",
                "lon",
                "last_prod",
                "cum_oil_12",
                "cum_gas_12",
                "cum_oil_life",
                "cum_gas_life",
                "cum_boe_life",
                "total_proppant",
                "total_fluid",
                "stage_count",
                "frac_date",
                "til_date",
                "first_year",
                "fluid_bbl_per_ft",
                "proppant_lb_per_ft",
                "cum_boe_12_per_1000_ft",
                "cum_oil_12_per_1000_ft",
                "cum_gas_12_per_1000_ft",
                "distance_mi"
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "wellbore_key",
                "well_name",
                "operator",
                "formation",
                "cum_boe_12",
                "first_year",
                "first_prod",
                "lateral_length",
                "tvd_td",
                "basin",
                "subbasin",
                "state",
                "county",
                "last_prod",
                "cum_oil_12",
                "cum_gas_12",
                "cum_oil_life",
                "cum_gas_life",
                "cum_boe_life",
                "total_proppant",
                "total_fluid",
                "stage_count",
                "frac_date",
                "til_date",
                "fluid_bbl_per_ft",
                "proppant_lb_per_ft",
                "cum_boe_12_per_1000_ft",
                "cum_oil_12_per_1000_ft",
                "cum_gas_12_per_1000_ft",
                "distance_mi"
              ]
            },
            "description": "Order the wells by this field: any name `fields` takes except the coordinates, or `distance_mi` with `near`; an unknown name is a 400 with `details.allowed`.\n\nWells without a value come last either way; ties go by wellbore key, so `cursor` pages are stable. With `near`, `sort` replaces the distance order and the radius still filters."
          },
          {
            "name": "order",
            "in": "query",
            "description": "With `sort` (ignored without it): `desc`, largest or latest first, or `asc`.",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          {
            "name": "county",
            "in": "query",
            "description": "Only wells in these counties: exact names, case-insensitive, comma-separated, at most 50.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "operators",
            "in": "query",
            "style": "form",
            "explode": true,
            "description": "Only wells of these operators: exact names, case-insensitive. Repeat the parameter for each name (`operators=A&operators=B`), since operator names can contain commas; at most 50, each at most 100 characters (400 past either, with `details.max` and `details.count`). `operator` stays a substring match. GET /wells/facets lists the names.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 100
              },
              "maxItems": 50
            }
          },
          {
            "name": "lateral_length_min",
            "in": "query",
            "description": "Only wells whose `lateral_length` is at least this, in ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lateral_length_max",
            "in": "query",
            "description": "Only wells whose `lateral_length` is at most this, in ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "tvd_td_min",
            "in": "query",
            "description": "Only wells whose `tvd_td` is at least this, in ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "tvd_td_max",
            "in": "query",
            "description": "Only wells whose `tvd_td` is at most this, in ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_oil_12_min",
            "in": "query",
            "description": "Only wells whose `cum_oil_12` is at least this, in bbl.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_oil_12_max",
            "in": "query",
            "description": "Only wells whose `cum_oil_12` is at most this, in bbl.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_gas_12_min",
            "in": "query",
            "description": "Only wells whose `cum_gas_12` is at least this, in mcf.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_gas_12_max",
            "in": "query",
            "description": "Only wells whose `cum_gas_12` is at most this, in mcf.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_boe_12_min",
            "in": "query",
            "description": "Only wells whose `cum_boe_12` is at least this, in BOE.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_boe_12_max",
            "in": "query",
            "description": "Only wells whose `cum_boe_12` is at most this, in BOE.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_oil_life_min",
            "in": "query",
            "description": "Only wells whose `cum_oil_life` is at least this, in bbl.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_oil_life_max",
            "in": "query",
            "description": "Only wells whose `cum_oil_life` is at most this, in bbl.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_gas_life_min",
            "in": "query",
            "description": "Only wells whose `cum_gas_life` is at least this, in mcf.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_gas_life_max",
            "in": "query",
            "description": "Only wells whose `cum_gas_life` is at most this, in mcf.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_boe_life_min",
            "in": "query",
            "description": "Only wells whose `cum_boe_life` is at least this, in BOE.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_boe_life_max",
            "in": "query",
            "description": "Only wells whose `cum_boe_life` is at most this, in BOE.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "total_proppant_min",
            "in": "query",
            "description": "Only wells whose `total_proppant` is at least this, in lb.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "total_proppant_max",
            "in": "query",
            "description": "Only wells whose `total_proppant` is at most this, in lb.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "total_fluid_min",
            "in": "query",
            "description": "Only wells whose `total_fluid` is at least this, in bbl.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "total_fluid_max",
            "in": "query",
            "description": "Only wells whose `total_fluid` is at most this, in bbl.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "stage_count_min",
            "in": "query",
            "description": "Only wells whose `stage_count` is at least this, in stages.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "stage_count_max",
            "in": "query",
            "description": "Only wells whose `stage_count` is at most this, in stages.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "first_year_min",
            "in": "query",
            "description": "Only wells whose `first_year` is at least this, in years.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "first_year_max",
            "in": "query",
            "description": "Only wells whose `first_year` is at most this, in years.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "fluid_bbl_per_ft_min",
            "in": "query",
            "description": "Only wells whose `fluid_bbl_per_ft` is at least this, in bbl/ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "fluid_bbl_per_ft_max",
            "in": "query",
            "description": "Only wells whose `fluid_bbl_per_ft` is at most this, in bbl/ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "proppant_lb_per_ft_min",
            "in": "query",
            "description": "Only wells whose `proppant_lb_per_ft` is at least this, in lb/ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "proppant_lb_per_ft_max",
            "in": "query",
            "description": "Only wells whose `proppant_lb_per_ft` is at most this, in lb/ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_boe_12_per_1000_ft_min",
            "in": "query",
            "description": "Only wells whose `cum_boe_12_per_1000_ft` is at least this, in BOE per 1,000 ft of lateral.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_boe_12_per_1000_ft_max",
            "in": "query",
            "description": "Only wells whose `cum_boe_12_per_1000_ft` is at most this, in BOE per 1,000 ft of lateral.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_oil_12_per_1000_ft_min",
            "in": "query",
            "description": "Only wells whose `cum_oil_12_per_1000_ft` is at least this, in bbl per 1,000 ft of lateral.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_oil_12_per_1000_ft_max",
            "in": "query",
            "description": "Only wells whose `cum_oil_12_per_1000_ft` is at most this, in bbl per 1,000 ft of lateral.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_gas_12_per_1000_ft_min",
            "in": "query",
            "description": "Only wells whose `cum_gas_12_per_1000_ft` is at least this, in mcf per 1,000 ft of lateral.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_gas_12_per_1000_ft_max",
            "in": "query",
            "description": "Only wells whose `cum_gas_12_per_1000_ft` is at most this, in mcf per 1,000 ft of lateral.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "first_prod_min",
            "in": "query",
            "description": "Only wells whose `first_prod` is on or after this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "first_prod_max",
            "in": "query",
            "description": "Only wells whose `first_prod` is on or before this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "last_prod_min",
            "in": "query",
            "description": "Only wells whose `last_prod` is on or after this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "last_prod_max",
            "in": "query",
            "description": "Only wells whose `last_prod` is on or before this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "frac_date_min",
            "in": "query",
            "description": "Only wells whose `frac_date` is on or after this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "frac_date_max",
            "in": "query",
            "description": "Only wells whose `frac_date` is on or before this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "til_date_min",
            "in": "query",
            "description": "Only wells whose `til_date` is on or after this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "til_date_max",
            "in": "query",
            "description": "Only wells whose `til_date` is on or before this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "keys",
            "in": "query",
            "description": "Only these wells: wellbore keys, exact, comma-separated, such as `SB329-01414,SB329-01415`: a known list, such as a forecast's analogs, in one call.\n\nA repeated `keys` adds its list, and a repeat counts once. At most 50 keys (400 naming `keys` past it, with `details.max` and `details.count`). An empty `keys=` means every well; a value with no key, such as `,`, is a 400. A key the dataset lacks matches nothing, so read the response for which wells came back.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "Matching wells.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WellColumns"
                },
                "example": {
                  "format": "columns",
                  "count": 3,
                  "columns": {
                    "wellbore_key": [
                      "SB329-01414",
                      "SB329-01450",
                      "SB329-01459"
                    ],
                    "well_name": [
                      "EDMONDSON RANCH 13-25 1WA",
                      "EDMONDSON RANCH 13-25 3WA",
                      "EDMONDSON RANCH 13-25 4WA"
                    ],
                    "operator": [
                      "Sample Operator A",
                      "Sample Operator A",
                      "Sample Operator A"
                    ],
                    "formation": [
                      "WOLFCAMP A",
                      "WOLFCAMP A",
                      "WOLFCAMP A"
                    ],
                    "mid_lon": [
                      -101.98506,
                      -101.97946,
                      -101.97481
                    ],
                    "mid_lat": [
                      32.01887,
                      32.01829,
                      32.01881
                    ],
                    "shl_lon": [
                      -101.98123,
                      -101.98077,
                      -101.97457
                    ],
                    "shl_lat": [
                      32.0071,
                      32.0071,
                      32.00678
                    ],
                    "heel_lon": [
                      -101.98505,
                      null,
                      -101.9748
                    ],
                    "heel_lat": [
                      32.00855,
                      null,
                      32.00848
                    ],
                    "bhl_lon": [
                      -101.98507,
                      -101.97815,
                      -101.97482
                    ],
                    "bhl_lat": [
                      32.0292,
                      32.02948,
                      32.02913
                    ],
                    "cum_boe_12": [
                      185052,
                      364550,
                      271909
                    ],
                    "first_year": [
                      2015,
                      2015,
                      2015
                    ]
                  }
                }
              },
              "application/geo+json": {
                "schema": {
                  "$ref": "#/components/schemas/WellFeatureCollection"
                },
                "examples": {
                  "page": {
                    "summary": "A page of Wolfcamp A wells",
                    "value": {
                      "type": "FeatureCollection",
                      "count": 4294,
                      "next_cursor": "bzoy",
                      "features": [
                        {
                          "type": "Feature",
                          "id": "SB003-01031",
                          "geometry": {
                            "type": "Point",
                            "coordinates": [
                              -102.31973,
                              32.14931
                            ]
                          },
                          "properties": {
                            "wellbore_key": "SB003-01031",
                            "well_name": "ZELLER TRUST 23-35 4WA",
                            "operator": "Sample Operator C",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2013-05-10",
                            "lateral_length": 7270,
                            "tvd_td": 9326,
                            "cum_boe_12": 164448,
                            "shl_lon": -102.31967,
                            "shl_lat": 32.13784,
                            "heel_lon": -102.31956,
                            "heel_lat": 32.13931,
                            "bhl_lon": -102.31989,
                            "bhl_lat": 32.1593
                          }
                        },
                        {
                          "type": "Feature",
                          "id": "SB003-01043",
                          "geometry": {
                            "type": "Point",
                            "coordinates": [
                              -102.33816,
                              32.11485
                            ]
                          },
                          "properties": {
                            "wellbore_key": "SB003-01043",
                            "well_name": "GARRISON FARMS 18-19 3WA",
                            "operator": "Sample Operator C",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2014-04-28",
                            "lateral_length": 4750,
                            "tvd_td": 9441,
                            "cum_boe_12": 106178,
                            "shl_lon": -102.32884,
                            "shl_lat": 32.11327,
                            "heel_lon": -102.33041,
                            "heel_lat": 32.11475,
                            "bhl_lon": -102.34591,
                            "bhl_lat": 32.11496
                          }
                        }
                      ]
                    }
                  },
                  "near": {
                    "summary": "Within 2 mi of a point, nearest first",
                    "value": {
                      "type": "FeatureCollection",
                      "count": 110,
                      "next_cursor": "bzoy",
                      "features": [
                        {
                          "type": "Feature",
                          "id": "SB329-01452",
                          "geometry": {
                            "type": "Point",
                            "coordinates": [
                              -101.98092,
                              32.01883
                            ]
                          },
                          "properties": {
                            "wellbore_key": "SB329-01452",
                            "well_name": "EDMONDSON RANCH 13-25 4WB",
                            "operator": "Sample Operator A",
                            "formation": "WOLFCAMP B",
                            "first_prod": "2015-06-25",
                            "lateral_length": 7500,
                            "tvd_td": 9673,
                            "cum_boe_12": 227851,
                            "shl_lon": -101.98095,
                            "shl_lat": 32.0071,
                            "heel_lon": -101.98091,
                            "heel_lat": 32.00851,
                            "bhl_lon": -101.98093,
                            "bhl_lat": 32.02916,
                            "distance_mi": 0.1
                          }
                        },
                        {
                          "type": "Feature",
                          "id": "SB329-01492",
                          "geometry": {
                            "type": "Point",
                            "coordinates": [
                              -101.97884,
                              32.01898
                            ]
                          },
                          "properties": {
                            "wellbore_key": "SB329-01492",
                            "well_name": "EDMONDSON RANCH 13-25 5WB",
                            "operator": "Sample Operator A",
                            "formation": "WOLFCAMP B",
                            "first_prod": "2015-06-28",
                            "lateral_length": 7480,
                            "tvd_td": 9718,
                            "cum_boe_12": 162298,
                            "shl_lon": -101.98086,
                            "shl_lat": 32.0071,
                            "heel_lon": -101.97883,
                            "heel_lat": 32.00865,
                            "bhl_lon": -101.97885,
                            "bhl_lat": 32.0293,
                            "distance_mi": 0.1
                          }
                        }
                      ]
                    }
                  },
                  "sorted": {
                    "summary": "Long laterals since 2021 by 12-month BOE",
                    "value": {
                      "type": "FeatureCollection",
                      "count": 5354,
                      "next_cursor": "bzoy",
                      "features": [
                        {
                          "type": "Feature",
                          "id": "SB329-06121",
                          "geometry": {
                            "type": "Point",
                            "coordinates": [
                              -101.96966,
                              31.80831
                            ]
                          },
                          "properties": {
                            "wellbore_key": "SB329-06121",
                            "well_name": "LUCKETT 32-44 1WA",
                            "cum_boe_12": 754067,
                            "county": "MIDLAND",
                            "cum_boe_12_per_1000_ft": 59096
                          }
                        },
                        {
                          "type": "Feature",
                          "id": "SB317-05524",
                          "geometry": {
                            "type": "Point",
                            "coordinates": [
                              -102.13022,
                              32.29035
                            ]
                          },
                          "properties": {
                            "wellbore_key": "SB317-05524",
                            "well_name": "BREWSTER FARMS 20-32 6WB",
                            "cum_boe_12": 727409,
                            "county": "MARTIN",
                            "cum_boe_12_per_1000_ft": 48494
                          }
                        }
                      ],
                      "applied": {
                        "sort": "cum_boe_12",
                        "order": "desc",
                        "lateral_length_min": 10000,
                        "first_prod_min": "2021-01-01"
                      }
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/wells/{key}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WellKey"
        }
      ],
      "get": {
        "operationId": "getWell",
        "tags": [
          "Wells"
        ],
        "summary": "Get a well",
        "description": "A well's header: operator, location, formation, lateral, TVD, completions, dates and cumulative production. Send `fields` to skip the header fields you don't need, and `include=floors` to learn which values may start at the dataset's first production month rather than at the well's own start.",
        "parameters": [
          {
            "name": "fields",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Only these fields, comma-separated; absent or empty, every field. `wellbore_key` is always kept, and the response keeps its own key order.\n\nAllowed: any of the well's header fields listed below.\n\nHeader fields: `wellbore_key`, `well_name`, `operator`, `basin`, `subbasin`, `state`, `county`, `formation`, `lateral_length`, `tvd_td`, `shl_lat`, `shl_lon`, `bhl_lat`, `bhl_lon`, `heel_lat`, `heel_lon`, `lat`, `lon`, `first_prod`, `last_prod`, `cum_oil_12`, `cum_gas_12`, `cum_boe_12`, `cum_oil_life`, `cum_gas_life`, `cum_boe_life`, `total_proppant`, `total_fluid`, `stage_count`, `frac_date`, `til_date`.\n\nFor example `well_name,tvd_td`. `fields` is checked before the well is looked up, so a bad name is a 400 whatever the key.\n\nNames are top-level only (no dots), case-sensitive and never empty; one not allowed here is a 400 with the allowed names in `details.allowed`."
          },
          {
            "name": "include",
            "in": "query",
            "description": "`floors` adds `floored`: the names of this answer's fields whose value may start at the dataset's first production month, not at the well's own start.\n\nThe record starts in that month (GET /dataset `first_production`), so a well whose first production falls in it may have produced earlier, unless its `til_date` is in that month too (the rule `exclude_floor` uses on POST /wells/typecurve). Such a well's `first_prod` is the floor month, and its `cum_*_12` and `cum_*_life` count only from it: show them as \"before <month>\" or \"since <month>\", not as facts. The values don't change.\n\n`floored` lists only fields this answer has (with `fields`, those asked), is `[]` for a well that isn't floored, and is absent without `include`; an empty value is the same as none. Any other nonempty value, or one named twice, is a 400 with details.field include, checked before the well is looked up.",
            "schema": {
              "type": "string",
              "enum": [
                "floors"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The well.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Well"
                },
                "example": {
                  "wellbore_key": "SB329-01414",
                  "well_name": "EDMONDSON RANCH 13-25 1WA",
                  "operator": "Sample Operator A",
                  "basin": "PERMIAN",
                  "subbasin": "MIDLAND",
                  "state": "TX",
                  "county": "MIDLAND",
                  "formation": "WOLFCAMP A",
                  "lateral_length": 7510,
                  "tvd_td": 9162,
                  "shl_lat": 32.007104,
                  "shl_lon": -101.981228,
                  "bhl_lat": 32.029199,
                  "bhl_lon": -101.985072,
                  "heel_lat": 32.008551,
                  "heel_lon": -101.985054,
                  "lat": 32.018152,
                  "lon": -101.98315,
                  "first_prod": "2015-06-26",
                  "last_prod": "2026-09-25",
                  "cum_oil_12": 146740,
                  "cum_gas_12": 229870,
                  "cum_boe_12": 185052,
                  "cum_oil_life": 493678,
                  "cum_gas_life": 1184974,
                  "cum_boe_life": 691174,
                  "total_proppant": 10776850,
                  "total_fluid": 357476,
                  "stage_count": 26,
                  "frac_date": "2015-05-14",
                  "til_date": "2015-06-25"
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/wells/{key}/production": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WellKey"
        }
      ],
      "get": {
        "operationId": "getWellProduction",
        "tags": [
          "Wells"
        ],
        "summary": "Get a well's production",
        "description": "Monthly production by ip_day: daily average rates over each period and cumulative volumes to its end.",
        "responses": {
          "200": {
            "description": "Production history.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Production"
                },
                "example": {
                  "wellbore_key": "SB329-01414",
                  "count": 3,
                  "units": {
                    "oil": "bbl/d",
                    "gas": "mcf/d",
                    "water": "bbl/d",
                    "cum_oil": "bbl",
                    "cum_gas": "mcf",
                    "cum_water": "bbl"
                  },
                  "rows": [
                    {
                      "date": "2015-06-26",
                      "ip_day": 1,
                      "oil": 49,
                      "gas": 62,
                      "water": 966,
                      "cum_oil": 49,
                      "cum_gas": 62,
                      "cum_water": 966
                    },
                    {
                      "date": "2015-07-25",
                      "ip_day": 30,
                      "oil": 489.48,
                      "gas": 631.76,
                      "water": 1423.34,
                      "cum_oil": 14244,
                      "cum_gas": 18383,
                      "cum_water": 42243
                    },
                    {
                      "date": "2015-08-24",
                      "ip_day": 60,
                      "oil": 577.73,
                      "gas": 779.97,
                      "water": 1282.3,
                      "cum_oil": 31576,
                      "cum_gas": 41782,
                      "cum_water": 80712
                    }
                  ]
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/wells/{key}/spacing": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WellKey"
        }
      ],
      "get": {
        "operationId": "getWellSpacing",
        "tags": [
          "Wells"
        ],
        "summary": "Get a well's spacing neighbors",
        "description": "The well's spacing: its node (azimuth, heel, pad) and each neighbor with position (lateral, stack, stagger), cone, parent or nonparent, signed and minimum offsets in ft, overlap and the neighbor's location. Offsets are from this well: xy + is right of it looking heel to toe, TVD + is deeper. `node` is null for wells spacing couldn't place (no location, TVD or date).",
        "responses": {
          "200": {
            "description": "Spacing node and neighbors.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WellSpacing"
                },
                "example": {
                  "wellbore_key": "SB329-01414",
                  "node": {
                    "wellbore_key": "SB329-01414",
                    "azimuth": 0.807573,
                    "heel_is_virtual": false,
                    "heel_lon": -101.985054,
                    "heel_lat": 32.008551,
                    "pad_id": 278,
                    "pad_wells": 6
                  },
                  "neighbors": [
                    {
                      "neighbor": "SB329-01390",
                      "position": "stack",
                      "cone": "stackbelow",
                      "category": "nonparent",
                      "signedxy": -62.084594,
                      "signedtvd": 568,
                      "minxy": 62.084594,
                      "mintvd": 568,
                      "mintangent": 571.382969,
                      "overlap": 0.990889,
                      "edge_date": "2015-06-26",
                      "well_name": "EDMONDSON RANCH 13-25 2WB",
                      "operator": "Sample Operator A",
                      "formation": "WOLFCAMP B",
                      "first_prod": "2015-05-21",
                      "bhl_lon": -101.985273,
                      "bhl_lat": 32.029011,
                      "heel_lon": -101.985254,
                      "heel_lat": 32.008363
                    },
                    {
                      "neighbor": "SB329-01393",
                      "position": "stagger",
                      "cone": "rightstaggerbelow",
                      "category": "nonparent",
                      "signedxy": 662.739425,
                      "signedtvd": 510,
                      "minxy": 662.739425,
                      "mintvd": 510,
                      "mintangent": 836.25567,
                      "overlap": 0.990721,
                      "edge_date": "2015-06-26",
                      "well_name": "EDMONDSON RANCH 13-25 3WB",
                      "operator": "Sample Operator A",
                      "formation": "WOLFCAMP B",
                      "first_prod": "2015-06-26",
                      "bhl_lon": -101.983054,
                      "bhl_lat": 32.029009,
                      "heel_lon": -101.982794,
                      "heel_lat": 32.008395
                    }
                  ]
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/wells/{key}/features": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WellKey"
        }
      ],
      "get": {
        "operationId": "getWellFeatures",
        "tags": [
          "Wells"
        ],
        "summary": "Get a well's spacing features",
        "description": "The well's spacing features at its latest ip_day, as its set's dataset was built: depletion, spacing counts and distances, drainage areas and the closest neighbors per position, plus each neighbor's impact columns (prefix `novi_spacing_neighbor_` removed).",
        "responses": {
          "200": {
            "description": "The well's spacing features.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WellFeatures"
                },
                "example": {
                  "wellbore_key": "SB329-01414",
                  "ip_day": 4110,
                  "features": {
                    "novi_ip_day": 4110,
                    "novi_depletion": 1744029.376202,
                    "novi_net_depletion": 1386553.376202,
                    "novi_spacing_is_child": false,
                    "novi_spacing_parent_count": 0,
                    "novi_spacing_nonparent_count": 10,
                    "novi_spacing_parent_in_formation": "NO PARENT",
                    "novi_spacing_wells_in_radius": 10,
                    "novi_spacing_boundedness_score": 5,
                    "novi_spacing_minxy": 662.739425,
                    "novi_spacing_drainage_area": 1012848.06868,
                    "novi_spacing_lateralcloser_id": "SB329-01534",
                    "novi_spacing_lateralcloser_mintangent": 1073.232217
                  },
                  "neighbors": [
                    {
                      "neighbor": "SB329-01390",
                      "calc_fluid_per_length": 41.6,
                      "calc_proppant_per_length": 1774,
                      "daysonline": 4145,
                      "impact_factor": 0.051133,
                      "in_formation": false,
                      "prior_oil": 0,
                      "relative_distance": "closer"
                    }
                  ]
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/subsurface": {
      "get": {
        "operationId": "getSubsurface",
        "tags": [
          "Subsurface"
        ],
        "summary": "Describe the subsurface model",
        "description": "The subsurface dataset, interpolation config, formations, rock properties and every grid with its unit. Structural depth is subsea ft (negative below sea level), the grid as the model set stores it; POST /tvd-estimates and POST /gun-barrels give tops in the set's TVD datum (`tvd_datum`). Thickness is ft; BVI is a fraction.",
        "responses": {
          "200": {
            "description": "Subsurface model.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubsurfaceModel"
                },
                "example": {
                  "dataset": {
                    "id": 9001,
                    "name": "SAMPLE_Midland_Sep2026",
                    "build_num": "S20260930"
                  },
                  "config": {
                    "id": 1,
                    "method": "linear",
                    "calc_epsg": 32139,
                    "params": {
                      "distance_from_grids": 3,
                      "distance_from_grids_units": "mi"
                    }
                  },
                  "formations": [
                    "DEAN",
                    "JO MILL",
                    "LOWER SPRABERRY SHALE",
                    "MIDDLE SPRABERRY",
                    "WOLFCAMP A",
                    "WOLFCAMP B",
                    "WOLFCAMP C",
                    "WOLFCAMP D"
                  ],
                  "properties": [
                    "novi_bvi_avg",
                    "novi_bvi_ofnet",
                    "novi_structuraldepth",
                    "novi_thickness_avg",
                    "novi_thickness_ofnet"
                  ],
                  "grids": [
                    {
                      "feature_name": "novi_structuraldepth_middle_spraberry",
                      "formation": "MIDDLE SPRABERRY",
                      "rock_property": "novi_structuraldepth",
                      "unit": "ft"
                    },
                    {
                      "feature_name": "novi_thickness_avg_middle_spraberry",
                      "formation": "MIDDLE SPRABERRY",
                      "rock_property": "novi_thickness_avg",
                      "unit": "ft"
                    },
                    {
                      "feature_name": "novi_thickness_ofnet_middle_spraberry",
                      "formation": "MIDDLE SPRABERRY",
                      "rock_property": "novi_thickness_ofnet",
                      "unit": "ft"
                    }
                  ]
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/subsurface/grids/{feature_name}": {
      "parameters": [
        {
          "name": "feature_name",
          "in": "path",
          "required": true,
          "description": "Grid name from GET /subsurface, as novi_structuraldepth_wolfcamp_a.",
          "schema": {
            "type": "string"
          },
          "example": "novi_structuraldepth_wolfcamp_a"
        }
      ],
      "get": {
        "operationId": "getSubsurfaceGrid",
        "tags": [
          "Subsurface"
        ],
        "summary": "Get a grid's points",
        "description": "A grid's lattice points as parallel `lng`, `lat` and `val` arrays, its value range (with 2nd and 98th percentiles for color ramps) and, when the points sit on a regular lng/lat lattice, its origin, steps and size. Points outside the formation's footprint are left out, so rebuild the lattice from `lattice` and treat missing points as no data.",
        "responses": {
          "200": {
            "description": "Grid points.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubsurfaceGrid"
                },
                "example": {
                  "feature_name": "novi_structuraldepth_wolfcamp_a",
                  "formation": "WOLFCAMP A",
                  "rock_property": "novi_structuraldepth",
                  "unit": "ft",
                  "count": 31513,
                  "range": {
                    "min": -9281.1,
                    "p02": -9175.4,
                    "p98": -8164.9,
                    "max": -8090.4
                  },
                  "lattice": {
                    "lng0": -102.633231,
                    "lat0": 31.064938,
                    "step_lng": 0.008535,
                    "step_lat": 0.00725,
                    "nx": 177,
                    "ny": 207
                  },
                  "lng": [
                    -101.805379,
                    -101.796844,
                    -101.916328
                  ],
                  "lat": [
                    31.064938,
                    31.064938,
                    31.072188
                  ],
                  "val": [
                    -9006.4,
                    -8991.1,
                    -9174
                  ]
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/subsurface/sample": {
      "get": {
        "operationId": "sampleSubsurface",
        "tags": [
          "Subsurface"
        ],
        "summary": "Sample grids along a well",
        "description": "Every grid interpolated (linear, on each lattice's triangulation) where the set reads its grids (GET /model-sets?include=subsurface_sampling): at the bottom hole, the surface hole or both averaged, as the models see a well.\n\n**Values.** Each value's distance to its grid is in `_novi_dist` (see `values`); a point outside a grid takes its nearest point's value. A point farther than `distance_from_grids` from a grid is left out of that grid's value, which is null when no point has one. With a formation, the bare property names (`novi_bvi_avg`, ...) hold that formation's values.",
        "parameters": [
          {
            "name": "shl",
            "in": "query",
            "required": true,
            "description": "Surface hole, `lng,lat`.",
            "schema": {
              "type": "string"
            },
            "example": "-101.93,31.93"
          },
          {
            "name": "bhl",
            "in": "query",
            "required": true,
            "description": "Bottom hole, `lng,lat`.",
            "schema": {
              "type": "string"
            },
            "example": "-101.93,31.957"
          },
          {
            "name": "formation",
            "in": "query",
            "description": "Target formation, case-insensitive.",
            "schema": {
              "type": "string"
            },
            "example": "WOLFCAMP A"
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "Interpolated values.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubsurfaceSample"
                },
                "example": {
                  "formation": "WOLFCAMP A",
                  "shl": [
                    -101.93,
                    31.93
                  ],
                  "bhl": [
                    -101.93,
                    31.957
                  ],
                  "values": {
                    "novi_bvi_avg": 0.051963,
                    "novi_bvi_avg_wolfcamp_a": 0.051963,
                    "novi_bvi_ofnet": 0.059711,
                    "novi_bvi_ofnet_wolfcamp_a": 0.059711,
                    "novi_min_grid_dist": 0,
                    "novi_structuraldepth": -8910.330485,
                    "novi_structuraldepth_wolfcamp_a": -8910.330485,
                    "novi_thickness_avg": 432.538212,
                    "novi_thickness_avg_wolfcamp_a": 432.538212,
                    "novi_thickness_ofnet": 312.778815,
                    "novi_thickness_ofnet_wolfcamp_a": 312.778815
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/wells/{key}/subsurface": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WellKey"
        }
      ],
      "get": {
        "operationId": "getWellSubsurface",
        "tags": [
          "Subsurface"
        ],
        "summary": "Get a well's subsurface column",
        "description": "A well's subsurface column: each formation's top, base, gross and net thickness and BVI at this well, in rock-column order, with the well's landing on the same axis. `include=inferred` fills gaps from offset wells.\n\n**The column.** Every formation the model set grids, shallowest first, in the rock column POST /gun-barrels draws its horizons in, a depth pack's TVD-only grids included. Formations on one surface keep GET /formations order; formations with no place in the column, the well's own among them when no grid names it, follow in GET /formations order. A structure grid named novi_structuraldepth or novi_structural_depth is the top, the first when a formation has both. Grids whose formation is `all` (fault distances, a CO2 band and the like) are in `well_wide`; a formation's grids beyond the five are in its `other`.\n\n**Values.** Each value's `state` is `mapped`, `inferred` or `none`, and every null carries a `reason`. Mapped values are interpolated where the set reads its grids, as GET /subsurface/sample reads them, not picked on this well's logs. Depths are on the `datum` axis: ft relative to sea level, negative below it (the opposite sign to a gun barrel's TVDss), or, where the depth pack declares KB TVD structure grids, ft below KB, positive down.\n\n**Landing.** `landing` is the well's own formation's landing: its depth below its formation's top at the bottom hole, placed under the column's top.\n\n- It comes from the header TVD (POST /gun-barrels' estimate for a placeholder header, a multiple of 500 ft) less the KB elevation at the surface hole, the TVDss POST /gun-barrels gives with `datum: \"subsea\"`. A pack whose wells are subsea takes the TVD as it is.\n- With survey stations in the depth pack, it follows POST /gun-barrels' order: survey, placeholder estimate, zone move, deeper-end read.\n- It is null, with a `reason`, without a depth pack that has ground elevation or subsea wells, where the pack has no ground elevation, or, with no survey to place it, without a header TVD or at a placeholder header with no estimate.\n\n**Inferred values.** `include=inferred` fills nulls from offset wells by the first rule that applies, and adds `offset_wells`, `unassigned`, a `summary` and the fixed `params`. Mapped values never change.\n\n- Rule 1, closure: a gross thickness is this formation's mapped top to the next formation's mapped top below it (`rule: closure`, grade high, `plus_minus` null), only while every formation the set grids has a place in the column; otherwise the reason names the one that hasn't.\n- Rule 2, offsets: wells whose midpoint lies within 1.5 mi of this well's, same pad first, then nearest: the first 8 with the value mapped, at least 3, weighted by inverse distance squared.\n- Under rule 2, a top is its `anchor`'s mapped top (the nearest formation above with one) plus the offsets' weighted mean distance below it. Gross and BVI are weighted means; net is their weighted net-to-gross times this well's gross.\n- Rule 3, fit: between two mapped tops, the inferred gross thicknesses, scaled by one factor (`scale`), fill the gap, each inferred top at the base above it. It fits when the thicknesses come within 15% of the gap and the factor within 15% of 1; else each mismatch is in `unassigned`.\n- Rule 4, grade: high with at least 5 offsets, every one within 1 mi, and a coefficient of variation (CV) under 10%; medium with a CV under 25%. Otherwise the value stays none, with a reason after \"Not inferred:\" naming the count or the CV.\n- A top's CV is taken on its distance below the anchor. An inferred net takes the lower grade of its net-to-gross and gross. `plus_minus` is the offsets' weighted standard deviation, scaled with a fitted gross. Offsets aren't limited by fault block.\n\n**Display only.** No forecast, plan or model input reads these values.",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "description": "`inferred` fills null values from offset wells by the four rules above and adds offset_wells, unassigned, summary and params. Absent: grid samples only.",
            "schema": {
              "type": "string",
              "enum": [
                "inferred"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The column, the landing and, with include=inferred, the inference.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WellSubsurface"
                },
                "examples": {
                  "mapped": {
                    "summary": "Grid samples, with reasons on nulls",
                    "value": {
                      "wellbore_key": "FX-S01",
                      "formation": "WOLFCAMP A",
                      "datum": {
                        "datum": "kb",
                        "kb_offset_ft": 23.5,
                        "elevation_source": "Sample tilted ground",
                        "subsea": true
                      },
                      "formations": [
                        {
                          "formation": "DEAN",
                          "label": "Dean",
                          "top_ft": {
                            "value": null,
                            "state": "none",
                            "grid_distance_mi": 4.273,
                            "reason": "Surface and bottom hole average 4.3 mi from the grid; limit 3 mi"
                          },
                          "base_ft": {
                            "value": null,
                            "state": "none",
                            "reason": "No top at this well"
                          },
                          "gross_ft": {
                            "value": null,
                            "state": "none",
                            "grid_distance_mi": 4.273,
                            "reason": "Surface and bottom hole average 4.3 mi from the grid; limit 3 mi"
                          },
                          "net_ft": {
                            "value": null,
                            "state": "none",
                            "grid_distance_mi": 4.273,
                            "reason": "Surface and bottom hole average 4.3 mi from the grid; limit 3 mi"
                          },
                          "bvi_avg": {
                            "value": null,
                            "state": "none",
                            "grid_distance_mi": 4.273,
                            "reason": "Surface and bottom hole average 4.3 mi from the grid; limit 3 mi"
                          },
                          "bvi_net": {
                            "value": null,
                            "state": "none",
                            "grid_distance_mi": 4.273,
                            "reason": "Surface and bottom hole average 4.3 mi from the grid; limit 3 mi"
                          },
                          "other": []
                        },
                        {
                          "formation": "WOLFCAMP A",
                          "label": "Wolfcamp A",
                          "top_ft": {
                            "value": -8183.7,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "base_ft": {
                            "value": -8562.9,
                            "state": "mapped"
                          },
                          "gross_ft": {
                            "value": 379.2,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "net_ft": {
                            "value": 259.1,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "bvi_avg": {
                            "value": 0.03672,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "bvi_net": {
                            "value": 0.041615,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "other": []
                        },
                        {
                          "formation": "WOLFCAMP B",
                          "label": "Wolfcamp B",
                          "top_ft": {
                            "value": -8562.9,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "base_ft": {
                            "value": -8938.2,
                            "state": "mapped"
                          },
                          "gross_ft": {
                            "value": 375.3,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "net_ft": {
                            "value": 262.3,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "bvi_avg": {
                            "value": 0.036432,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "bvi_net": {
                            "value": 0.041517,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "other": []
                        }
                      ],
                      "well_wide": [],
                      "landing": {
                        "formation": "WOLFCAMP A",
                        "depth_ft": -8333.3,
                        "tvd_from": "header",
                        "source": "Header TVD 11,355 ft less 3,021 ft KB elevation at the surface hole: 8,334 ft below sea level, 150 ft below the Wolfcamp A top at the bottom hole"
                      }
                    }
                  },
                  "inferred": {
                    "summary": "include=inferred: nulls filled from offset wells",
                    "value": {
                      "wellbore_key": "FX-S01",
                      "formation": "WOLFCAMP A",
                      "datum": {
                        "datum": "kb",
                        "kb_offset_ft": 23.5,
                        "elevation_source": "Sample tilted ground",
                        "subsea": true
                      },
                      "formations": [
                        {
                          "formation": "DEAN",
                          "label": "Dean",
                          "top_ft": {
                            "value": null,
                            "state": "none",
                            "grid_distance_mi": 4.273,
                            "reason": "Surface and bottom hole average 4.3 mi from the grid; limit 3 mi. Not inferred: 1 offset within 1.5 mi with mapped Dean and Lower Spraberry Shale tops, need 3"
                          },
                          "base_ft": {
                            "value": null,
                            "state": "none",
                            "reason": "No top at this well"
                          },
                          "gross_ft": {
                            "value": null,
                            "state": "none",
                            "grid_distance_mi": 4.273,
                            "reason": "Surface and bottom hole average 4.3 mi from the grid; limit 3 mi. Not inferred: 1 offset within 1.5 mi with a mapped Dean gross thickness, need 3"
                          },
                          "net_ft": {
                            "value": null,
                            "state": "none",
                            "grid_distance_mi": 4.273,
                            "reason": "Surface and bottom hole average 4.3 mi from the grid; limit 3 mi. Not inferred: No gross thickness at this well to apply net-to-gross to"
                          },
                          "bvi_avg": {
                            "value": null,
                            "state": "none",
                            "grid_distance_mi": 4.273,
                            "reason": "Surface and bottom hole average 4.3 mi from the grid; limit 3 mi. Not inferred: 1 offset within 1.5 mi with a mapped Dean BVI average, need 3"
                          },
                          "bvi_net": {
                            "value": null,
                            "state": "none",
                            "grid_distance_mi": 4.273,
                            "reason": "Surface and bottom hole average 4.3 mi from the grid; limit 3 mi. Not inferred: 1 offset within 1.5 mi with a mapped Dean BVI net, need 3"
                          },
                          "other": []
                        },
                        {
                          "formation": "WOLFCAMP B",
                          "label": "Wolfcamp B",
                          "top_ft": {
                            "value": -8562.9,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "base_ft": {
                            "value": -8938.2,
                            "state": "mapped"
                          },
                          "gross_ft": {
                            "value": 375.3,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "net_ft": {
                            "value": 262.3,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "bvi_avg": {
                            "value": 0.036432,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "bvi_net": {
                            "value": 0.041517,
                            "state": "mapped",
                            "grid_distance_mi": 0
                          },
                          "other": []
                        },
                        {
                          "formation": "WOLFCAMP C",
                          "label": "Wolfcamp C",
                          "top_ft": {
                            "value": -8938.3,
                            "state": "inferred",
                            "rule": "offsets",
                            "grade": "medium",
                            "offsets": 4,
                            "farthest_mi": 1.3,
                            "plus_minus": 2.4,
                            "anchor": "WOLFCAMP B",
                            "scale": 1.043
                          },
                          "base_ft": {
                            "value": -9350.2,
                            "state": "inferred",
                            "grade": "medium"
                          },
                          "gross_ft": {
                            "value": 411.9,
                            "state": "inferred",
                            "rule": "offsets",
                            "grade": "medium",
                            "offsets": 4,
                            "farthest_mi": 1.3,
                            "plus_minus": 0.5,
                            "scale": 1.043
                          },
                          "net_ft": {
                            "value": 201.1,
                            "state": "inferred",
                            "rule": "offsets",
                            "grade": "medium",
                            "offsets": 4,
                            "farthest_mi": 1.3,
                            "plus_minus": 1.2
                          },
                          "bvi_avg": {
                            "value": 0.02755,
                            "state": "inferred",
                            "rule": "offsets",
                            "grade": "medium",
                            "offsets": 4,
                            "farthest_mi": 1.3,
                            "plus_minus": 0.00012645
                          },
                          "bvi_net": {
                            "value": 0.029075,
                            "state": "inferred",
                            "rule": "offsets",
                            "grade": "medium",
                            "offsets": 4,
                            "farthest_mi": 1.3,
                            "plus_minus": 0.00010058
                          },
                          "other": []
                        },
                        {
                          "formation": "WOLFCAMP D",
                          "label": "Wolfcamp D",
                          "top_ft": {
                            "value": -9350.1,
                            "state": "mapped",
                            "grid_distance_mi": 1.968
                          },
                          "base_ft": {
                            "value": -9703.9,
                            "state": "mapped"
                          },
                          "gross_ft": {
                            "value": 353.8,
                            "state": "mapped",
                            "grid_distance_mi": 1.968
                          },
                          "net_ft": {
                            "value": 195.8,
                            "state": "mapped",
                            "grid_distance_mi": 1.968
                          },
                          "bvi_avg": {
                            "value": 0.032018,
                            "state": "mapped",
                            "grid_distance_mi": 1.968
                          },
                          "bvi_net": {
                            "value": 0.034622,
                            "state": "mapped",
                            "grid_distance_mi": 1.968
                          },
                          "other": []
                        }
                      ],
                      "well_wide": [],
                      "landing": {
                        "formation": "WOLFCAMP A",
                        "depth_ft": -8333.3,
                        "tvd_from": "header",
                        "source": "Header TVD 11,355 ft less 3,021 ft KB elevation at the surface hole: 8,334 ft below sea level, 150 ft below the Wolfcamp A top at the bottom hole"
                      },
                      "offset_wells": [
                        {
                          "wellbore_key": "FX-S02",
                          "well_name": "FIXTURE EDGE 2WA",
                          "distance_mi": 0.4,
                          "same_pad": false,
                          "used": [
                            {
                              "formation": "WOLFCAMP C",
                              "field": "top_below_anchor_ft",
                              "value": 411.2
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "gross_ft",
                              "value": 394.5
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "bvi_avg",
                              "value": 0.027454
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "bvi_net",
                              "value": 0.028998
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "net_to_gross",
                              "value": 0.49063
                            }
                          ]
                        },
                        {
                          "wellbore_key": "FX-S03",
                          "well_name": "FIXTURE EDGE 3LS",
                          "distance_mi": 0.7,
                          "same_pad": false,
                          "used": [
                            {
                              "formation": "WOLFCAMP C",
                              "field": "top_below_anchor_ft",
                              "value": 416.6
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "gross_ft",
                              "value": 395.5
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "bvi_avg",
                              "value": 0.027716
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "bvi_net",
                              "value": 0.029207
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "net_to_gross",
                              "value": 0.4845
                            }
                          ]
                        },
                        {
                          "wellbore_key": "FX-S04",
                          "well_name": "FIXTURE EDGE 4WB",
                          "distance_mi": 1,
                          "same_pad": false,
                          "used": [
                            {
                              "formation": "WOLFCAMP C",
                              "field": "top_below_anchor_ft",
                              "value": 415.4
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "gross_ft",
                              "value": 395.5
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "bvi_avg",
                              "value": 0.027716
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "bvi_net",
                              "value": 0.029207
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "net_to_gross",
                              "value": 0.4845
                            }
                          ]
                        },
                        {
                          "wellbore_key": "FX-S05",
                          "well_name": "FIXTURE EDGE 5WA",
                          "distance_mi": 1.3,
                          "same_pad": false,
                          "used": [
                            {
                              "formation": "WOLFCAMP C",
                              "field": "top_below_anchor_ft",
                              "value": 414.3
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "gross_ft",
                              "value": 395.5
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "bvi_avg",
                              "value": 0.027716
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "bvi_net",
                              "value": 0.029207
                            },
                            {
                              "formation": "WOLFCAMP C",
                              "field": "net_to_gross",
                              "value": 0.4845
                            }
                          ]
                        }
                      ],
                      "unassigned": [],
                      "summary": {
                        "inferred": 5,
                        "refused": 5,
                        "offset_wells": 4,
                        "farthest_mi": 1.3
                      },
                      "params": {
                        "radius_mi": 1.5,
                        "max_offsets": 8,
                        "min_offsets": 3,
                        "weights": "inverse_distance_squared",
                        "fit_within": 0.15,
                        "high": {
                          "min_offsets": 5,
                          "within_mi": 1,
                          "max_cv": 0.1
                        },
                        "medium": {
                          "min_offsets": 3,
                          "within_mi": 1.5,
                          "max_cv": 0.25
                        },
                        "fault_blocks": "Not limited by fault block"
                      }
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/completions/defaults": {
      "get": {
        "operationId": "getCompletionDefaults",
        "tags": [
          "Design"
        ],
        "summary": "Get default completions",
        "description": "The fluid and proppant per ft a drawn well gets when you leave them blank: medians over wells brought online in the dataset's last 180 days. On a model set whose models read stage length, clusters per stage or frac rate, each such field's median over the same wells, less those without it, where they give one.",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "description": "`inputs` adds `inputs`: the completion fields the set's models read, each with its label, unit, default and the model inputs it feeds; any other value is a 400 with details.field include.",
            "schema": {
              "type": "string",
              "enum": [
                "inputs"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "Default completions.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompletionDefaults"
                },
                "examples": {
                  "defaults": {
                    "summary": "Defaults",
                    "value": {
                      "fluid_bbl_per_ft": 55.2,
                      "proppant_lb_per_ft": 2716,
                      "source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                      "wells": 1572,
                      "window": {
                        "start": "2026-04-04",
                        "end": "2026-09-30",
                        "days": 180
                      },
                      "formations": [
                        {
                          "formation": "DEAN",
                          "fluid_bbl_per_ft": 54.5,
                          "proppant_lb_per_ft": 2799,
                          "wells": 53,
                          "source": "median of 53 DEAN wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "JO MILL",
                          "fluid_bbl_per_ft": 51.7,
                          "proppant_lb_per_ft": 2772,
                          "wells": 65,
                          "source": "median of 65 JO MILL wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "LOWER SPRABERRY SHALE",
                          "fluid_bbl_per_ft": 56.7,
                          "proppant_lb_per_ft": 2692,
                          "wells": 359,
                          "source": "median of 359 LOWER SPRABERRY SHALE wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "MIDDLE SPRABERRY",
                          "fluid_bbl_per_ft": 55.7,
                          "proppant_lb_per_ft": 2721,
                          "wells": 164,
                          "source": "median of 164 MIDDLE SPRABERRY wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "WOLFCAMP A",
                          "fluid_bbl_per_ft": 54.5,
                          "proppant_lb_per_ft": 2709.5,
                          "wells": 372,
                          "source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "WOLFCAMP B",
                          "fluid_bbl_per_ft": 54.55,
                          "proppant_lb_per_ft": 2719.5,
                          "wells": 456,
                          "source": "median of 456 WOLFCAMP B wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "WOLFCAMP C",
                          "fluid_bbl_per_ft": 58.5,
                          "proppant_lb_per_ft": 2628.5,
                          "wells": 28,
                          "source": "median of 28 WOLFCAMP C wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "WOLFCAMP D",
                          "fluid_bbl_per_ft": 55,
                          "proppant_lb_per_ft": 2725,
                          "wells": 75,
                          "source": "median of 75 WOLFCAMP D wells online 2026-04-04 to 2026-09-30"
                        }
                      ]
                    }
                  },
                  "inputs": {
                    "summary": "include=inputs",
                    "value": {
                      "fluid_bbl_per_ft": 55.2,
                      "proppant_lb_per_ft": 2716,
                      "source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                      "wells": 1572,
                      "window": {
                        "start": "2026-04-04",
                        "end": "2026-09-30",
                        "days": 180
                      },
                      "formations": [
                        {
                          "formation": "DEAN",
                          "fluid_bbl_per_ft": 54.5,
                          "proppant_lb_per_ft": 2799,
                          "wells": 53,
                          "source": "median of 53 DEAN wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "JO MILL",
                          "fluid_bbl_per_ft": 51.7,
                          "proppant_lb_per_ft": 2772,
                          "wells": 65,
                          "source": "median of 65 JO MILL wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "LOWER SPRABERRY SHALE",
                          "fluid_bbl_per_ft": 56.7,
                          "proppant_lb_per_ft": 2692,
                          "wells": 359,
                          "source": "median of 359 LOWER SPRABERRY SHALE wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "MIDDLE SPRABERRY",
                          "fluid_bbl_per_ft": 55.7,
                          "proppant_lb_per_ft": 2721,
                          "wells": 164,
                          "source": "median of 164 MIDDLE SPRABERRY wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "WOLFCAMP A",
                          "fluid_bbl_per_ft": 54.5,
                          "proppant_lb_per_ft": 2709.5,
                          "wells": 372,
                          "source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "WOLFCAMP B",
                          "fluid_bbl_per_ft": 54.55,
                          "proppant_lb_per_ft": 2719.5,
                          "wells": 456,
                          "source": "median of 456 WOLFCAMP B wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "WOLFCAMP C",
                          "fluid_bbl_per_ft": 58.5,
                          "proppant_lb_per_ft": 2628.5,
                          "wells": 28,
                          "source": "median of 28 WOLFCAMP C wells online 2026-04-04 to 2026-09-30"
                        },
                        {
                          "formation": "WOLFCAMP D",
                          "fluid_bbl_per_ft": 55,
                          "proppant_lb_per_ft": 2725,
                          "wells": 75,
                          "source": "median of 75 WOLFCAMP D wells online 2026-04-04 to 2026-09-30"
                        }
                      ],
                      "inputs": [
                        {
                          "field": "fluid_bbl_per_ft",
                          "label": "Fluid per ft",
                          "unit": "bbl/ft",
                          "required": true,
                          "default": 55.2,
                          "max": 1000,
                          "model_inputs": [
                            "novi_calc_fluid_per_length"
                          ]
                        },
                        {
                          "field": "proppant_lb_per_ft",
                          "label": "Proppant per ft",
                          "unit": "lb/ft",
                          "required": true,
                          "default": 2716,
                          "max": 20000,
                          "model_inputs": [
                            "novi_calc_proppant_per_length"
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/tvd-estimates": {
      "post": {
        "operationId": "estimateTvd",
        "tags": [
          "Design"
        ],
        "summary": "Estimate TVD for well paths",
        "description": "How deep each well would land in its formation: its formation's structure top at the well plus the median depth below that top at which nearby same-formation wells land. Forecasts make the same estimate when `tvd_ft` is blank.\n\n**Nearby wells.** Only wells with production (a `first_prod` date) and a header `tvd_td` that isn't a multiple of 500 ft count; such a header is taken for a placeholder, except in a set whose depth pack says its wells are subsea.\n\n- An estimate needs 3 of them. The search starts within about 2 miles and widens to about 4, then 8 miles (`source` names the distance; `wells_scope` stays nearby), then takes the formation-wide landing, which needs 3 too.\n- With no grid at the well, or neither landing, the estimate is the nearby wells' median TVD (`method: nearby_wells`). Fewer than 3 within about 8 miles gives `tvd_ft: null` and an `error`.\n\n**Checks.** `checks` flags an estimate at or below the next formation's top (`below_next_top`) or nearby wells that land outside the zone (`landing_far_from_formation`); see `checks`. Estimates aren't clamped to the zone, except in a set labelled from its own structure grids (`formation_labels` in GET /model-sets) with a depth pack: there a `structure_grid` estimate above its formation's top or below its base lands a foot inside the nearer one, and `source` says so and gives the median.\n\n**Landing fraction.** A well's `landing_fraction` lands it at that fraction of its formation's thickness, from the grids alone, as POST /forecasts lands one (see `landing_fraction`). Its answer adds `formation_base_ft` and `thickness_ft`; a well that can't be landed so gets `tvd_ft: null` and an `error` naming landing_fraction.\n\n**Depth packs.** A depth pack can hold TVD-only structure and thickness grids for formations the set's own model doesn't grid. Estimates, landing fields and gun-barrel tops use them as they use the set's; nothing else reads them (GET /subsurface, GET /formations, a forecast's subsurface values and model inputs, exports).\n\n**Datum.** Tops and TVDs are in the set's TVD datum.\n\n- With a depth pack (the answer carries `tvd_datum`), it is the wells' kelly bushing (KB), as header TVDs are: a top is the grid's subsea depth plus the KB elevation at the surface hole, and a nearby well's landing is its TVD less its own top. A pack can instead declare KB TVD structure grids.\n- Where the pack has no ground elevation, a nearby well is left out of the median, a well is estimated as one with no grid there, and an entered `landing_below_top_ft` or `landing_fraction` gets `tvd_ft: null` and an `error`.\n- Without a depth pack (no `tvd_datum`), tops are the grid's own subsea depth.",
        "requestBody": {
          "required": true,
          "description": "Well paths and formations, 1 to 1,000.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TvdEstimateRequest"
              },
              "example": {
                "wells": [
                  {
                    "shl": [
                      -101.93,
                      31.93
                    ],
                    "bhl": [
                      -101.93,
                      31.957
                    ],
                    "formation": "WOLFCAMP A"
                  },
                  {
                    "shl": [
                      -101.95,
                      31.86
                    ],
                    "bhl": [
                      -101.95,
                      31.89
                    ],
                    "formation": "LOWER SPRABERRY SHALE"
                  },
                  {
                    "shl": [
                      -101.93,
                      31.93
                    ],
                    "bhl": [
                      -101.93,
                      31.957
                    ],
                    "formation": "WOLFCAMP A",
                    "landing_fraction": 0.5
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One estimate per well, in request order.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TvdEstimateResponse"
                },
                "example": {
                  "estimates": [
                    {
                      "index": 0,
                      "formation": "WOLFCAMP A",
                      "tvd_ft": 9111,
                      "source": "WOLFCAMP A top 8,910 ft from the structure grid + 201 ft median landing below top (19 nearby wells)",
                      "method": "structure_grid",
                      "formation_top_ft": 8910,
                      "landing_below_top_ft": 201,
                      "wells_used": 19,
                      "wells_scope": "nearby"
                    },
                    {
                      "index": 1,
                      "formation": "LOWER SPRABERRY SHALE",
                      "tvd_ft": 8478,
                      "source": "LOWER SPRABERRY SHALE top 8,182 ft from the structure grid + 296 ft median landing below top (17 nearby wells)",
                      "method": "structure_grid",
                      "formation_top_ft": 8182,
                      "landing_below_top_ft": 296,
                      "wells_used": 17,
                      "wells_scope": "nearby"
                    },
                    {
                      "index": 2,
                      "formation": "WOLFCAMP A",
                      "tvd_ft": 9127,
                      "source": "WOLFCAMP A top 8,910 ft from the structure grid + 0.5 of its 433 ft thickness (base from WOLFCAMP B)",
                      "method": "structure_grid",
                      "formation_top_ft": 8910,
                      "formation_base_ft": 9343,
                      "thickness_ft": 433
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/gun-barrels": {
      "post": {
        "operationId": "buildGunBarrel",
        "tags": [
          "Design"
        ],
        "summary": "Place wells in a gun barrel",
        "description": "A gun barrel (cross-section) of drawn and existing wells, with every formation's structure top across it. Each well is placed at its lateral's midpoint, across and along one section line.\n\n**What you send.** `wells` (drawn), `keys` (existing) or both, up to 200 in all. Keep a gun barrel to one pad or unit: wells far apart or at an angle still project at their midpoints. For a plan's wells, read them with GET /plans/{id}?include=wells and send their ends with `tvd_ft` from `estimates`.\n\n**The line.** Without `line`, the section runs square to the laterals (each heel to toe, flipped to agree with the first) through `center`, the mean of their midpoints, at their mean direction. `across_ft` is + right looking along `azimuth_deg`, as a spacing neighbor's `signedxy` for a well drilled that way. For parallel wells, the difference of two `across_ft` is their horizontal spacing and of two `tvd_ft` their vertical offset, + deeper (as `signedtvd`).\n\n**Well TVDs.** `tvd_source` says in words where each `tvd_ft` came from; `include: [\"tvd_from\"]` adds it as a code.\n\n- A drawn well's is the TVD a forecast would use: `tvd_ft` as sent, else its formation top + `landing_below_top_ft` or `landing_fraction` of its thickness, else POST /tvd-estimates' estimate.\n- An existing well's is its header `tvd_td`, or POST /tvd-estimates' estimate at its ends for a header that is a multiple of 500 ft (a placeholder, except in a set whose depth pack says its wells are subsea).\n- In a set labelled from its own structure grids (`formation_labels` in GET /model-sets) with a depth pack, an existing well whose header lies outside its formation is drawn a foot inside its nearer top or base.\n\n**Survey stations.** In a set whose depth pack carries them, an existing well's TVD is found in this order: its survey, the placeholder estimate, the move inside its formation, then the deeper-end read. These only draw wells: forecasts and POST /tvd-estimates still read header TVDs.\n\n- Survey: where its formation's grid reaches 3 or more of its lateral stations, `top_ft` plus the median of each station's TVD less the top there, whatever its header.\n- Deeper end: in a set where 95% of surveyed wells' header TVDs are within 5 ft of their deepest station, `top_ft` plus its header `tvd_td` less the top at its deeper end.\n- Both need ground elevation at the surface hole, unless the pack declares KB TVD structure grids; without it, the well is drawn as in a set without surveys.\n\n**Horizons.** Every formation with a structure grid, a depth pack's TVD-only grids included, top to bottom in the rock column, ranked from the grids as `landing_fraction` ranks its base, not in GET /formations order. Formations on one surface, and after them those with no place in the column (no grid value at any sample point), follow GET /formations order. When the column can't be built (no subsurface model), all come in GET /formations order, and the next call tries again. `top_ft` is the well's own formation's top, averaged at its surface and bottom holes; it and the horizon tops are in the set's TVD datum (see `top_ft`).\n\n**KB along the line.** With a pack that has an elevation grid, a horizon sample's KB elevation is taken at the mean along position of the placed wells' surface holes, so a well can sit off its horizon by up to the ground's change between its surface hole and that position. It is averaged at the section's two ends instead when:\n\n- the surface holes spread along the line by more than half of `along_range_ft` (wells drilled from both ends, each then off by about half the ground's change between the ends);\n- no placed well has a surface hole location; or\n- that line would leave any well's `top_ft` further from its own horizon than the two-end line does.\n\nA well whose surface hole lies off its lateral also misses its horizon by up to the grid's change between its surface hole and the section's ends. Stacked wells under different ground can't share one KB line: each misses it by its own KB elevation's difference from the line's.\n\nA sample with no ground elevation at its point (on the two-end line, at either end) is null, never bridged.\n\n**Subsea depths.** `datum: \"subsea\"` answers in ft below sea level, to compare wells whatever their KB elevation (see `datum`). A subsea answer is for drawing: the `tvd_ft` you send stays KB, so send an edit as a landing (`landing_below_top_ft` from that answer's `top_ft`, or `landing_fraction`) or a KB `tvd_ft` from an answer without `datum`.\n\n**Errors.** A well whose TVD can't be found, or an existing well without both ends, comes back with nulls and an `error`, not a 400. When no well has both ends, the answer is a 400 naming `keys`.",
        "requestBody": {
          "required": true,
          "description": "Drawn wells, existing keys or both, 200 in all, and optionally the line to measure about and the extras to add.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GunBarrelRequest"
              },
              "examples": {
                "laterals": {
                  "summary": "The line from the laterals",
                  "value": {
                    "wells": [
                      {
                        "shl": [
                          -101.98292,
                          32.008551
                        ],
                        "bhl": [
                          -101.98293,
                          32.029199
                        ],
                        "formation": "WOLFCAMP B",
                        "landing_below_top_ft": 40
                      }
                    ],
                    "keys": [
                      "SB329-01414",
                      "SB329-01450"
                    ],
                    "include": [
                      "ends",
                      "tvd_from"
                    ]
                  }
                },
                "line": {
                  "summary": "About a pad's line",
                  "value": {
                    "wells": [
                      {
                        "shl": [
                          -101.98292,
                          32.008551
                        ],
                        "bhl": [
                          -101.98293,
                          32.029199
                        ],
                        "formation": "WOLFCAMP B",
                        "landing_below_top_ft": 40
                      }
                    ],
                    "keys": [
                      "SB329-01414",
                      "SB329-01450"
                    ],
                    "line": {
                      "center": [
                        -101.982925,
                        32.018875
                      ],
                      "azimuth_deg": 0
                    },
                    "include": [
                      "ends",
                      "tvd_from"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The line, the horizons and the wells, drawn wells first, in request order.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GunBarrel"
                },
                "example": {
                  "azimuth_deg": 1.9,
                  "center": [
                    -101.982482,
                    32.018681
                  ],
                  "along_range_ft": [
                    -4204,
                    3983
                  ],
                  "sample_across_ft": [
                    -1460,
                    -1307,
                    -1154,
                    -1001,
                    -848,
                    -695,
                    -542,
                    -389,
                    -236,
                    -83,
                    70,
                    223,
                    376,
                    529,
                    682,
                    835,
                    988,
                    1141,
                    1294,
                    1447,
                    1600
                  ],
                  "horizons": [
                    {
                      "formation": "WOLFCAMP A",
                      "top_ft": [
                        8984,
                        8984,
                        8983,
                        8983,
                        8983,
                        8982,
                        8982,
                        8981,
                        8981,
                        8981,
                        8980,
                        8980,
                        8979,
                        8979,
                        8978,
                        8978,
                        8978,
                        8977,
                        8977,
                        8976,
                        8976
                      ]
                    },
                    {
                      "formation": "WOLFCAMP B",
                      "top_ft": [
                        9392,
                        9391,
                        9391,
                        9390,
                        9390,
                        9389,
                        9389,
                        9389,
                        9388,
                        9388,
                        9387,
                        9387,
                        9386,
                        9385,
                        9385,
                        9384,
                        9384,
                        9383,
                        9383,
                        9382,
                        9382
                      ]
                    },
                    {
                      "formation": "WOLFCAMP C",
                      "top_ft": [
                        10036,
                        10036,
                        10036,
                        10036,
                        10036,
                        10036,
                        10036,
                        10036,
                        10036,
                        10036,
                        10036,
                        10035,
                        10035,
                        10035,
                        10035,
                        10035,
                        10035,
                        10035,
                        10035,
                        10035,
                        10035
                      ]
                    }
                  ],
                  "wells": [
                    {
                      "kind": "drawn",
                      "index": 0,
                      "formation": "WOLFCAMP B",
                      "across_ft": -139,
                      "along_ft": 66,
                      "heel_along_ft": -3698,
                      "toe_along_ft": 3830,
                      "tvd_ft": 9428,
                      "tvd_source": "WOLFCAMP B top 9,388 ft from the structure grid + 40 ft entered landing below top",
                      "tvd_from": "landing",
                      "top_ft": 9388
                    },
                    {
                      "kind": "existing",
                      "wellbore_key": "SB329-01414",
                      "well_name": "EDMONDSON RANCH 13-25 1WA",
                      "first_prod": "2015-06-26",
                      "formation": "WOLFCAMP A",
                      "across_ft": -800,
                      "along_ft": 44,
                      "heel_along_ft": -3720,
                      "toe_along_ft": 3808,
                      "tvd_ft": 9162,
                      "tvd_source": "header",
                      "tvd_from": "header",
                      "top_ft": 8981
                    },
                    {
                      "kind": "existing",
                      "wellbore_key": "SB329-01450",
                      "well_name": "EDMONDSON RANCH 13-25 3WA",
                      "first_prod": "2015-06-28",
                      "formation": "WOLFCAMP A",
                      "across_ft": 940,
                      "along_ft": -110,
                      "heel_along_ft": -4204,
                      "toe_along_ft": 3983,
                      "tvd_ft": 9150,
                      "tvd_source": "header",
                      "tvd_from": "header",
                      "top_ft": 8978
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/land-grid": {
      "get": {
        "operationId": "getLandGrid",
        "tags": [
          "Design"
        ],
        "summary": "Get the land survey grid in a bbox",
        "description": "Texas original land survey lines and labels inside `bbox`: the county, block, section and abstract lines landmen lease by, as the Railroad Commission of Texas (RRC) maps them, to draw under wells and pads.\n\n**Levels.** `level` picks how fine: `block` gives county and block lines and a label per block in each county it spans; `section` (the default) adds section and survey lines and numbers; `abstract` adds abstract lines and numbers. A label's `text` gives its form.\n\n**What you get.** One MultiLineString feature per kind of line (`properties.line`), with each line whose extent overlaps the bbox whole, not clipped, and Point labels inside the bbox, each inside its largest parcel. `coverage` lists the counties the grid holds (outside them every answer is empty), and `source` says where it comes from and its date. The lines are digitized from General Land Office maps in NAD27 and shifted to NAD83: a picture to plan by, not a legal survey. Every model set answers alike, from the default dataset.\n\n**Limits.** The bbox's area, width × height in square degrees, is capped per level: block 16, section 1, abstract 1; past it, a 400 names the cap. Fetch blocks for a whole county or more, sections and abstracts for a few townships. A dataset without the land grid is a 503.",
        "parameters": [
          {
            "name": "bbox",
            "in": "query",
            "required": true,
            "description": "`west,south,east,north` in degrees, west < east and south < north; its area may be at most 16 square degrees at block, 1 square degrees at section, 1 square degrees at abstract.",
            "schema": {
              "type": "string"
            },
            "example": "-101.84,31.86,-101.82,31.88"
          },
          {
            "name": "level",
            "in": "query",
            "description": "block: county and block lines with block labels; section (default): adds section lines and numbers; abstract: adds abstract division lines and numbers.",
            "schema": {
              "type": "string",
              "enum": [
                "block",
                "section",
                "abstract"
              ],
              "default": "section"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The lines and labels in the bbox.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LandGrid"
                },
                "example": {
                  "type": "FeatureCollection",
                  "level": "section",
                  "bbox": [
                    -101.84,
                    31.86,
                    -101.82,
                    31.88
                  ],
                  "coverage": {
                    "state": "TX",
                    "counties": [
                      "003",
                      "135",
                      "173",
                      "227",
                      "317",
                      "329",
                      "383",
                      "461"
                    ]
                  },
                  "source": "Synthetic sample land grid as of 2026-09-30: invented blocks, sections and abstracts, not Railroad Commission data; not a legal survey",
                  "features": [
                    {
                      "type": "Feature",
                      "geometry": {
                        "type": "MultiLineString",
                        "coordinates": [
                          [
                            [
                              -102.29,
                              31.65
                            ],
                            [
                              -101.78,
                              31.65
                            ],
                            [
                              -101.78,
                              32.09
                            ],
                            [
                              -102.29,
                              32.09
                            ],
                            [
                              -102.29,
                              31.65
                            ]
                          ]
                        ]
                      },
                      "properties": {
                        "kind": "line",
                        "line": "county"
                      }
                    },
                    {
                      "type": "Feature",
                      "geometry": {
                        "type": "MultiLineString",
                        "coordinates": [
                          [
                            [
                              -101.83,
                              31.855501
                            ],
                            [
                              -101.83,
                              31.87
                            ]
                          ]
                        ]
                      },
                      "properties": {
                        "kind": "line",
                        "line": "block"
                      }
                    },
                    {
                      "type": "Feature",
                      "geometry": {
                        "type": "MultiLineString",
                        "coordinates": [
                          [
                            [
                              -101.847073,
                              31.87
                            ],
                            [
                              -101.83,
                              31.87
                            ]
                          ]
                        ]
                      },
                      "properties": {
                        "kind": "line",
                        "line": "section"
                      }
                    },
                    {
                      "type": "Feature",
                      "geometry": {
                        "type": "Point",
                        "coordinates": [
                          -101.838536,
                          31.86275
                        ]
                      },
                      "properties": {
                        "kind": "label",
                        "level": "section",
                        "text": "19",
                        "county_fips": "329",
                        "abstract": null,
                        "survey": "SAMPLE RR CO",
                        "block": "S7",
                        "section": "19"
                      }
                    },
                    {
                      "type": "Feature",
                      "geometry": {
                        "type": "Point",
                        "coordinates": [
                          -101.838536,
                          31.87725
                        ]
                      },
                      "properties": {
                        "kind": "label",
                        "level": "section",
                        "text": "13",
                        "county_fips": "329",
                        "abstract": null,
                        "survey": "SAMPLE RR CO",
                        "block": "S7",
                        "section": "13"
                      }
                    }
                  ]
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/layouts/fill": {
      "post": {
        "operationId": "fillLayout",
        "tags": [
          "Design"
        ],
        "summary": "Fill an area with wells",
        "description": "Parallel wells across a polygon: lines `spacing_ft` apart at `azimuth_deg`, clipped to it. Wells are drilled toward the azimuth, so 0 puts surface holes at the south end. Send the wells to POST /plans to forecast them together.\n\n**Wells per line.** With `lateral_length_ft`, each line's chord holds as many wells of that length as fit end to end.\n\n- Without it, one well per chord, edge to edge, dropping chords under 95% of the longest. A kept chord over 30,000 ft (between its rounded ends) becomes the fewest equal wells of at most 30,000 ft, toe to heel; the 95% rule still compares whole chords.\n- Chords under 1,000 ft are skipped.\n- With `setback_ft` (a lease-line setback), every point of every lateral is at least that far from every side, concave areas included.\n\n**Even side gaps.** The lines start centered across the width (less the setback each side), then move together, by at most half a spacing, so the outermost wells sit as far from the outline on the left as on the right.\n\n- A gap runs across the azimuth, from an outermost well to the outline's edges beside it within 45° of the azimuth; holes and standoff laterals don't count.\n- The lines stop when the gaps are within 1 ft, or as close as up to 3 more fills get them; a move that leaves them more than 1 ft apart must narrow the difference by at least 1 ft.\n- A move counts only if every bench keeps its count of wells and 99% of its lateral footage, and every lateral stays 100 to 50,000 ft long.\n- Each extra fill runs only within the work limit (see Work limit), so the largest fills keep their centered lines.\n\n**Units.** Send `area` instead of `polygon` to fill a unit as POST /areas reads it (its `geometry`) or as POST /units/summary takes it. Each part of a MultiPolygon is filled on its own, and each well carries `part`, its index. Holes are left out: a line's chords stop at a hole's edge, each piece kept by the length rule. A hole that isn't inside its outline is a 400; holes are checked in order up to a fixed amount of checking per request, and past it a hole is taken as sent. POST /forecasts and POST /plans ignore a well's `part` and `bench`.\n\n**Benches.** `benches` (1 to 10) fills several benches at once, each with its own `spacing_ft` or `wells_per_section`, `offset_ft` and `formation`. Wells come part by part, then bench by bench; each carries `bench`, its index, and `formation` when its bench (or the request) names one.\n\n**Standoff.** `standoff_ft` keeps every lateral that far from the existing laterals in its bench's formation that POST /wells/search finds with the same area, `match: lateral`, `buffer_ft` = `standoff_ft` and that formation (the echo's `standoff_wells`). Chords are cut around them, each piece kept by the length rule. It needs a formation for every bench (the request's `formation` without benches).\n\n**Pads.** `wells_per_pad` groups the wells into pads of that many: per part, by tier (a well's place along its line, heel first), then across the azimuth left to right looking along it, benches together. Each well carries `pad`, and the echo's `pads` counts them.\n\n**Evening out.** Each part evens out its side gaps on its own, every bench's lines moved alike; the gaps are those of the part's outermost wells, of any bench. A part with a non-zero bench `offset_ft` isn't evened out, and in a plan's `layouts` one on any layout's bench keeps every layout of the plan centered, so a stagger set across layouts holds.\n\n**Work limit.** A fill that needs more work than one request may take (about a second) is a 400 \"too complex\" with `details.max_work` and `details.work`. Work is each part's lines times its ring edges (counted twice with `setback_end_ft`) plus the bench's standoff laterals, summed over parts and benches, at most 1,000,000 (for a plan's `layouts`, in all).\n\nEvening out never makes a fill refused: it runs only while the work stays within the limit (for `layouts`, what their own fills leave, layout by layout in order), so a fill near the limit keeps its centered lines. The same request always fares the same: simplify the outline, widen the spacing, or send fewer benches or a smaller `standoff_ft`.",
        "requestBody": {
          "required": true,
          "description": "The area and the layout.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FillLayoutRequest"
              },
              "examples": {
                "polygon": {
                  "summary": "A polygon",
                  "value": {
                    "polygon": [
                      [
                        -101.95,
                        31.93
                      ],
                      [
                        -101.93,
                        31.93
                      ],
                      [
                        -101.93,
                        31.95
                      ],
                      [
                        -101.95,
                        31.95
                      ]
                    ],
                    "azimuth_deg": 0,
                    "spacing_ft": 880,
                    "lateral_length_ft": null
                  }
                },
                "unit": {
                  "summary": "A holed unit, two benches, heel and toe setbacks, standoff and pads",
                  "value": {
                    "area": {
                      "type": "Polygon",
                      "coordinates": [
                        [
                          [
                            -101.95,
                            31.93
                          ],
                          [
                            -101.93,
                            31.93
                          ],
                          [
                            -101.93,
                            31.96
                          ],
                          [
                            -101.95,
                            31.96
                          ],
                          [
                            -101.95,
                            31.93
                          ]
                        ],
                        [
                          [
                            -101.945,
                            31.945
                          ],
                          [
                            -101.94,
                            31.945
                          ],
                          [
                            -101.94,
                            31.94
                          ],
                          [
                            -101.945,
                            31.94
                          ],
                          [
                            -101.945,
                            31.945
                          ]
                        ]
                      ]
                    },
                    "azimuth_deg": 0,
                    "setback_ft": 330,
                    "setback_end_ft": 467,
                    "min_lateral_ft": 4346,
                    "benches": [
                      {
                        "wells_per_section": 6,
                        "formation": "WOLFCAMP A"
                      },
                      {
                        "spacing_ft": 1320,
                        "offset_ft": 440,
                        "formation": "WOLFCAMP B"
                      }
                    ],
                    "standoff_ft": 150,
                    "wells_per_pad": 4
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The wells, left to right looking along the azimuth: west to east for an azimuth strictly between -90 and 90 or past 270 either way, the default 0 included.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FillLayoutResponse"
                },
                "examples": {
                  "edge": {
                    "summary": "Edge to edge",
                    "value": {
                      "count": 8,
                      "azimuth_deg": 0,
                      "spacing_ft": 880,
                      "lateral_length_ft": null,
                      "wells": [
                        {
                          "shl": [
                            -101.9499274,
                            31.93
                          ],
                          "bhl": [
                            -101.9499274,
                            31.95
                          ],
                          "lateral_length_ft": 7276
                        },
                        {
                          "shl": [
                            -101.947091,
                            31.93
                          ],
                          "bhl": [
                            -101.947091,
                            31.95
                          ],
                          "lateral_length_ft": 7276
                        }
                      ]
                    }
                  },
                  "setback": {
                    "summary": "setback_ft: 330",
                    "value": {
                      "count": 7,
                      "azimuth_deg": 0,
                      "spacing_ft": 880,
                      "lateral_length_ft": null,
                      "setback_ft": 330,
                      "wells": [
                        {
                          "shl": [
                            -101.9485092,
                            31.9309085
                          ],
                          "bhl": [
                            -101.9485092,
                            31.9490915
                          ],
                          "lateral_length_ft": 6615
                        },
                        {
                          "shl": [
                            -101.9456728,
                            31.9309085
                          ],
                          "bhl": [
                            -101.9456728,
                            31.9490915
                          ],
                          "lateral_length_ft": 6615
                        }
                      ]
                    }
                  },
                  "unit": {
                    "summary": "The unit request, three of its wells",
                    "value": {
                      "count": 8,
                      "azimuth_deg": 0,
                      "lateral_length_ft": null,
                      "setback_ft": 330,
                      "setback_end_ft": 467,
                      "min_lateral_ft": 4346,
                      "standoff_ft": 150,
                      "standoff_wells": 18,
                      "wells_per_pad": 4,
                      "pads": 2,
                      "wells_per_section": 10,
                      "benches": [
                        {
                          "spacing_ft": 880,
                          "wells_per_section": 6,
                          "offset_ft": 0,
                          "formation": "WOLFCAMP A",
                          "count": 4
                        },
                        {
                          "spacing_ft": 1320,
                          "wells_per_section": 4,
                          "offset_ft": 440,
                          "formation": "WOLFCAMP B",
                          "count": 4
                        }
                      ],
                      "wells": [
                        {
                          "shl": [
                            -101.9428364,
                            31.9462851
                          ],
                          "bhl": [
                            -101.9428364,
                            31.9587149
                          ],
                          "lateral_length_ft": 4522,
                          "formation": "WOLFCAMP A",
                          "part": 0,
                          "bench": 0,
                          "pad": 0
                        },
                        {
                          "shl": [
                            -101.94,
                            31.9462851
                          ],
                          "bhl": [
                            -101.94,
                            31.9587149
                          ],
                          "lateral_length_ft": 4522,
                          "formation": "WOLFCAMP A",
                          "part": 0,
                          "bench": 0,
                          "pad": 0
                        },
                        {
                          "shl": [
                            -101.947091,
                            31.9344426
                          ],
                          "bhl": [
                            -101.947091,
                            31.9587149
                          ],
                          "lateral_length_ft": 8830,
                          "formation": "WOLFCAMP B",
                          "part": 0,
                          "bench": 1,
                          "pad": 0
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/areas": {
      "post": {
        "operationId": "readAreas",
        "tags": [
          "Design"
        ],
        "summary": "Read areas from a shapefile, GeoJSON, KML or KMZ",
        "description": "Polygons from a zipped shapefile, a GeoJSON file, or a Google Earth KML or KMZ as named WGS 84 areas, each with its acres, long axis and a ring ready to fill. Nothing is stored: send the file again to read it again.\n\n**Upload.** Send the file as `multipart/form-data`, as `curl -F file=@units.zip -F crs=EPSG:2277 <origin>/api/v1/areas`. JSON-only clients, such as MCP tools, send `shapefile` or `kmz` (base64), `geojson` or `kml` in a JSON body; the answer is the same.\n\n**Shapefiles.** The zip's first polygon layer is read (a warning names the others). Polygon, PolygonZ and PolygonM shapes are read in 2D: clockwise rings are outer rings and counterclockwise ones holes, each in the smallest outer ring holding it (a hole in none is read as an outer ring, with a warning). The .dbf's attributes become `properties`, decoded as the .cpg says, else UTF-8 when valid, else Windows-1252. Null shapes and records the .dbf marks deleted (ArcGIS hides them) are in `skipped`; other areas keep their record index as `id`.\n\n**GeoJSON.** A FeatureCollection, Feature, Polygon or MultiPolygon; other geometries are in `skipped`.\n\n**KML and KMZ.** Every Placemark at any depth is a record, numbered from 0, whose Polygons, directly or in a MultiGeometry, are its parts. Coordinates are lon,lat[,alt] tuples of at most 64 characters, altitude dropped; a Placemark with any other is in `skipped`, as are other geometries, and a MultiGeometry's other members are left out with a warning. Properties are name, description, and ExtendedData by name. A KMZ's KML is its root doc.kml (any case), else its first .kml, with a warning naming any others. Network links aren't fetched.\n\nA DTD is a 400. An entity XML doesn't define (HTML's `&nbsp;`; any XML name of up to 40 characters) is kept as written, with a warning; in an element the reader uses, a bare `&` or any other text between `&` and `;` is a 400.\n\n**Holes.** A hole lies inside the ring it is cut from. One wholly outside it is read as an outer ring, a part of its own; one that crosses it or is as large is left out; each with a warning, and `acres`, `parts` and `holes` describe the area as read. Holes are checked in file order up to a fixed amount of checking per request; past it, that hole and every later one are taken as the file gives them.\n\n**Coordinate systems.** The request's `crs`; else the file's own (its .prj or GeoJSON `crs` member; WGS 84 for GeoJSON in degrees and for KML); else the first supported system that puts up to 256 sampled vertices all within 0.5° of the dataset's bbox, in preference order: NAD83 state plane in US survey feet, then metres, NAD83(2011), the Texas-wide systems, CONUS Albers, Web Mercator, UTM, degrees, NAD27 last. When none does, degrees are read as WGS 84 with a warning, and other numbers are a 400 on `crs`.\n\n`crs.alternatives` lists the other systems that fit, each with `offset_ft`, the farthest a vertex would move in it (international-foot variants have `code: null`); `max_offset_ft` is the largest, and a warning says the areas are only that sure. When it matters, send `crs`. A .prj that puts the areas off the dataset is still used, with a warning naming a system that fits. NAD27 is shifted to NAD83 with NOAA's NADCON conus grid, within about 0.2 m of NOAA's NCAT at Permian points; NAD83, NAD83(2011) and WGS 84 are taken as the same, within about 2 m.\n\n**Names.** From `name_field`, else the first of name, unit_name, unitname, lease_name, leasename, padname, pad_name, dsu, unit, lease that 90% of areas fill, else the first text field whose name is at most 100 characters and whose values all differ, else `Area <id + 1>`. `name_fields` joins several fields' values instead, cut at 200 characters; names need not differ, and an area whose fields are all blank is `Area <id + 1>`. Send `name_field` or `name_fields`, not both.\n\n**Measures.** `acres` and `long_axis_azimuth_deg` (as the Pad Optimizer takes it) are measured in flat-earth feet about each part.\n\n**Fill.** `fill.polygon` is the largest part's outer ring, at most 500 corners, ready for POST /layouts/fill or a `layout`. To fill every part with the holes left out, send the area's `geometry` as `area` there instead.\n\n**Limits.**\n\n- The 10 MB request body.\n- 5,000 areas, 200,000 vertices and 20,000 rings, each a 400 with `details.max` and `details.count`.\n- 50 properties an area and 500 property names a file, later ones left out with a warning (the asked name fields are always read).\n- A zip of 64 entries (a KMZ 1,000, its KML at most 10 MB unzipped), stored or deflated, each at most 32 MB and 64 MB in all, not encrypted or ZIP64.\n- A .prj of at most 16 KB; a .cpg over 16 KB is ignored.\n- About a second of reading and geometry work, past which the file is a 400 as too complex, with `details.max_work`. The same file always gets the same answer.\n\n**Errors.** 400 with `details.field` naming the input: the file's field, `crs` (with `details.supported`), `name_field` or `name_fields[i]` (with `details.fields` for a field the file lacks), `name_fields`, `name_separator`, `body` (not JSON or valid multipart) or an unknown multipart part's name. A body over 10 MB is a 413.",
        "requestBody": {
          "required": true,
          "description": "The file: uploaded as multipart/form-data, or in a JSON body for clients limited to JSON.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/AreasUpload"
              },
              "encoding": {
                "file": {
                  "contentType": "application/zip, application/geo+json, application/json, application/vnd.google-earth.kml+xml, application/vnd.google-earth.kmz"
                }
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AreasRequest"
              },
              "examples": {
                "geojson": {
                  "summary": "GeoJSON",
                  "value": {
                    "geojson": {
                      "type": "FeatureCollection",
                      "features": [
                        {
                          "type": "Feature",
                          "properties": {
                            "name": "Pecos Draw Unit",
                            "lease_no": "PD-17",
                            "gross_acres": 1280
                          },
                          "geometry": {
                            "type": "Polygon",
                            "coordinates": [
                              [
                                [
                                  -101.95,
                                  31.93
                                ],
                                [
                                  -101.93,
                                  31.93
                                ],
                                [
                                  -101.93,
                                  31.96
                                ],
                                [
                                  -101.95,
                                  31.96
                                ],
                                [
                                  -101.95,
                                  31.93
                                ]
                              ],
                              [
                                [
                                  -101.945,
                                  31.94
                                ],
                                [
                                  -101.94,
                                  31.94
                                ],
                                [
                                  -101.94,
                                  31.945
                                ],
                                [
                                  -101.945,
                                  31.945
                                ],
                                [
                                  -101.945,
                                  31.94
                                ]
                              ]
                            ]
                          }
                        }
                      ]
                    }
                  }
                },
                "shapefile": {
                  "summary": "A zipped shapefile in base64",
                  "value": {
                    "shapefile": "UEsDBBQAAAAAAIVNUV2Rt74t7AAAAOwAAAAHAAAAcGFkLnNocAAAJwoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAHboAwAABQAAAM3MzMzMfFnArkfhehTuP0DsUbgehXtZwDMzMzMz8z9AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAAAQAUAAADNzMzMzHxZwK5H4XoU7j9A7FG4HoV7WcAzMzMzM/M/QAEAAAAFAAAAAAAAAM3MzMzMfFnArkfhehTuP0DNzMzMzHxZwDMzMzMz8z9A7FG4HoV7WcAzMzMzM/M/QOxRuB6Fe1nArkfhehTuP0DNzMzMzHxZwK5H4XoU7j9AUEsDBBQAAAAAAIVNUV0XN5RjbAAAAGwAAAAHAAAAcGFkLnNoeAAAJwoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADboAwAABQAAAM3MzMzMfFnArkfhehTuP0DsUbgehXtZwDMzMzMz8z9AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAyAAAAQFBLAwQUAAAAAACFTVFd50Ma0EcAAABHAAAABwAAAHBhZC5kYmYDfgoRAQAAAEEABQAAAAAAAAAAAAAAAAAAAAAAAAAAAElEAAAAAAAAAAAATgAAAAAEAAAAAAAAAAAAAAAAAAAADSAgICAxGlBLAwQUAAAAAACFTVFdVX9Dr5EAAACRAAAABwAAAHBhZC5wcmpHRU9HQ1NbIkdDU19XR1NfMTk4NCIsREFUVU1bIkRfV0dTXzE5ODQiLFNQSEVST0lEWyJXR1NfMTk4NCIsNjM3ODEzNy4wLDI5OC4yNTcyMjM1NjNdXSxQUklNRU1bIkdyZWVud2ljaCIsMC4wXSxVTklUWyJEZWdyZWUiLDAuMDE3NDUzMjkyNTE5OTQzM11dUEsBAhQDFAAAAAAAhU1RXZG3vi3sAAAA7AAAAAcAAAAAAAAAAAAAAIABAAAAAHBhZC5zaHBQSwECFAMUAAAAAACFTVFdFzeUY2wAAABsAAAABwAAAAAAAAAAAAAAgAERAQAAcGFkLnNoeFBLAQIUAxQAAAAAAIVNUV3nQxrQRwAAAEcAAAAHAAAAAAAAAAAAAACAAaIBAABwYWQuZGJmUEsBAhQDFAAAAAAAhU1RXVV/Q6+RAAAAkQAAAAcAAAAAAAAAAAAAAIABDgIAAHBhZC5wcmpQSwUGAAAAAAQABADUAAAAxAIAAAAA"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The areas, in file order.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AreasResponse"
                },
                "example": {
                  "count": 1,
                  "name_field": "name",
                  "fields": [
                    "name",
                    "lease_no",
                    "gross_acres"
                  ],
                  "crs": {
                    "code": "EPSG:4326",
                    "name": "WGS 84",
                    "source": "file",
                    "datum_shift": null,
                    "max_offset_ft": 0,
                    "alternatives": []
                  },
                  "areas": [
                    {
                      "id": 0,
                      "name": "Pecos Draw Unit",
                      "properties": {
                        "name": "Pecos Draw Unit",
                        "lease_no": "PD-17",
                        "gross_acres": 1280
                      },
                      "geometry": {
                        "type": "Polygon",
                        "coordinates": [
                          [
                            [
                              -101.95,
                              31.93
                            ],
                            [
                              -101.93,
                              31.93
                            ],
                            [
                              -101.93,
                              31.96
                            ],
                            [
                              -101.95,
                              31.96
                            ],
                            [
                              -101.95,
                              31.93
                            ]
                          ],
                          [
                            [
                              -101.945,
                              31.945
                            ],
                            [
                              -101.94,
                              31.945
                            ],
                            [
                              -101.94,
                              31.94
                            ],
                            [
                              -101.945,
                              31.94
                            ],
                            [
                              -101.945,
                              31.945
                            ]
                          ]
                        ]
                      },
                      "acres": 1490.74,
                      "long_axis_azimuth_deg": 0,
                      "parts": 1,
                      "holes": 1,
                      "vertices": 8,
                      "in_dataset": true,
                      "fill": {
                        "polygon": [
                          [
                            -101.95,
                            31.93
                          ],
                          [
                            -101.93,
                            31.93
                          ],
                          [
                            -101.93,
                            31.96
                          ],
                          [
                            -101.95,
                            31.96
                          ]
                        ],
                        "simplified_from": null,
                        "max_deviation_ft": 0,
                        "dropped_parts": 0,
                        "dropped_holes": 1
                      }
                    }
                  ],
                  "skipped": [],
                  "warnings": [
                    "1 area has holes or several parts. A layout uses the largest part and keeps wells out of its holes."
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/areas/fill": {
      "post": {
        "operationId": "fillAreas",
        "tags": [
          "Design"
        ],
        "summary": "Fill many areas with wells",
        "description": "Lays wells of one lateral length over many areas in one call, laying areas that touch as one piece of land. Nothing is stored: send the wells to POST /plans, each with a formation, to forecast them.\n\n**Areas.** Send `areas`, `lateral_length_ft`, and `spacing_ft` or `benches`. `azimuth_deg`, `setback_ft`, `setback_end_ft`, `wells_per_pad` and `formation` work as in POST /layouts/fill.\n\n**Pieces of land.** The areas not skipped are grouped part by part, and each group is laid on one grid. Two parts join when their edges run opposite ways within 1 ft of each other along an unbroken 100 ft, however each side's corners fall, or when they overlap. A shared corner, or points touching here and there, don't join. A MultiPolygon's parts may fall in different groups.\n\n- Two parts overlap when an edge of one crosses an edge of the other, their edges run the same way along such a stretch, or a corner of one lies inside the other (when every corner lies on the other's edges, an edge's midpoint).\n- In a group, a well runs across the lines between areas but never through a hole or outside the group, and land two areas cover is laid once.\n- `setback_ft` and `setback_end_ft` hold from the group's outer edges and holes only, not from edges its parts share. An edge inside an overlap isn't shared, so it still holds them.\n\n**Length.** Along each line, an unbroken stretch of L ft, less its setbacks, holds k = floor(L / `lateral_length_ft`) wells of `lateral_length_ft`, toe to heel and centred, and none when k is 0. When the land left, L less k lengths, is at least `min_lateral_ft`, it takes k + 1 wells of L / (k + 1) instead. An L within a millionth of a foot of a whole number of lengths takes that many full wells.\n\n- With 2-mile laterals and no setbacks, three one-mile sections take one 2-mile well, centred; two 5,200 ft sections one of 10,400 ft; four, two of 10,400 ft.\n- With one-mile laterals and the default `min_lateral_ft`, a one-mile section less 330 ft end setbacks still takes one well, of 4,620 ft.\n- A well that measures over `lateral_length_ft` is shortened about its middle.\n- Lengths and setbacks are laid on a flat grid about the group's first corner, so far from it a well can measure a little short and pass a little closer to an edge: about 30 miles from it at about 32° N, a 5,280 ft well measured 24 ft short and a 330 ft setback 328.95 ft.\n\n**Azimuth.** `azimuth_deg` sets every group's. Without it, each group runs along its largest part's longest outer edge or square to it, whichever way the group's outer corners span more feet; within 1 ft, along the edge. `groups[].azimuth_deg` gives each.\n\n**Order.** Groups come in the order of their first part (areas in request order, then parts). Wells come group by group, then bench by bench, then line by line across the azimuth, heel to toe; pads number on across groups. Side gaps aren't evened out. The same request always answers the same bytes.\n\n**Skipped areas.** Each is listed once in `skipped`, in request order, and counted in `areas.skipped`:\n\n- `outside_dataset`: its box misses GET /dataset `bbox`, as POST /areas' `in_dataset: false` says.\n- `degenerate`: a ring POST /layouts/fill's `area` would refuse: under 3 corners, a corner that isn't [lng, lat], no area, or a hole that isn't inside its outline.\n- `too_small`: its group lays no well, or no well runs through it.\n- `over_limit`: its group would pass the well limit or the fill work, or its holes need more checking than the request has left to show they lie inside their outlines.\n\n**Limits.**\n\n- At most 5,000 areas, 200,000 vertices in all, and `max_wells` wells: the lesser of GET /dataset `limits.plan_wells` and 10,000.\n- At most 35,000,000 of fill work. Per bench, each line a group lays costs its ring edges plus its setback edges (twice with `setback_end_ft`), plus 16 for each of those whose setback reaches the line; each part a laid well runs through costs 25.\n- Groups are laid in order with what is left, and a group past a limit is skipped whole while later groups still run. One whose lines times edges pass the work left counts no work; one that passes either limit while it is laid counts the work it did.\n\n**Errors.** A body over 10 MB is a 413. Other errors are 400 with `details.field`:\n\n- a missing or out-of-range number;\n- `spacing_ft` with `benches`, or neither;\n- `areas` empty, over 5,000 entries, or over 200,000 vertices in all (`details.max` and `details.count`);\n- an `area` that isn't a Polygon or MultiPolygon;\n- a repeated `id` (\"areas[i].id repeats areas[j].id\");\n- areas too complex to group within one request's work (`details.max_work`).",
        "requestBody": {
          "required": true,
          "description": "The areas, the lateral length and the layout.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FillAreasRequest"
              },
              "example": {
                "areas": [
                  {
                    "id": 1,
                    "area": {
                      "type": "Polygon",
                      "coordinates": [
                        [
                          [
                            -101.95,
                            31.93
                          ],
                          [
                            -101.933,
                            31.93
                          ],
                          [
                            -101.933,
                            31.9445
                          ],
                          [
                            -101.95,
                            31.9445
                          ],
                          [
                            -101.95,
                            31.93
                          ]
                        ]
                      ]
                    }
                  },
                  {
                    "id": 2,
                    "area": {
                      "type": "Polygon",
                      "coordinates": [
                        [
                          [
                            -101.95,
                            31.9445
                          ],
                          [
                            -101.933,
                            31.9445
                          ],
                          [
                            -101.933,
                            31.959
                          ],
                          [
                            -101.95,
                            31.959
                          ],
                          [
                            -101.95,
                            31.9445
                          ]
                        ]
                      ]
                    }
                  },
                  {
                    "id": 3,
                    "area": {
                      "type": "Polygon",
                      "coordinates": [
                        [
                          [
                            -96,
                            33
                          ],
                          [
                            -95.983,
                            33
                          ],
                          [
                            -95.983,
                            33.0145
                          ],
                          [
                            -96,
                            33.0145
                          ],
                          [
                            -96,
                            33
                          ]
                        ]
                      ]
                    }
                  }
                ],
                "lateral_length_ft": 10560,
                "spacing_ft": 880
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The wells, group by group, and what was skipped.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FillAreasResponse"
                },
                "example": {
                  "count": 6,
                  "lateral_length_ft": 10560,
                  "min_lateral_ft": 8976,
                  "azimuth_deg": null,
                  "spacing_ft": 880,
                  "join": {
                    "within_ft": 1,
                    "min_shared_ft": 100
                  },
                  "max_wells": 10000,
                  "areas": {
                    "sent": 3,
                    "used": 2,
                    "skipped": {
                      "outside_dataset": 1,
                      "degenerate": 0,
                      "too_small": 0,
                      "over_limit": 0
                    }
                  },
                  "groups": [
                    {
                      "areas": [
                        1,
                        2
                      ],
                      "azimuth_deg": 0,
                      "first": 0,
                      "count": 6
                    }
                  ],
                  "skipped": [
                    {
                      "id": 3,
                      "reason": "outside_dataset"
                    }
                  ],
                  "wells": [
                    {
                      "shl": [
                        -101.948591,
                        31.93
                      ],
                      "bhl": [
                        -101.948591,
                        31.959
                      ],
                      "lateral_length_ft": 10550,
                      "group": 0,
                      "areas": [
                        1,
                        2
                      ]
                    },
                    {
                      "shl": [
                        -101.9457546,
                        31.93
                      ],
                      "bhl": [
                        -101.9457546,
                        31.959
                      ],
                      "lateral_length_ft": 10550,
                      "group": 0,
                      "areas": [
                        1,
                        2
                      ]
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/area-sets": {
      "get": {
        "operationId": "listAreaSets",
        "tags": [
          "Design"
        ],
        "summary": "List area sets",
        "description": "The area sets the caller can read, newest first: each set's record, without its areas (GET one for those). A private set lists only for its creator. Invalid limit or cursor is 400. A server without a state store answers 409 \"Area sets need a state store; this server keeps plans in memory\".",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Page size, 1-100.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Area sets and next cursor.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AreaSetList"
                },
                "example": {
                  "items": [
                    {
                      "id": "7d1f3c2a-5b4e-4f6a-9c8d-2e1b0a9f8e7d",
                      "name": "Lease outlines",
                      "count": 1,
                      "acres": 1490.74,
                      "bbox": [
                        -101.95,
                        31.93,
                        -101.93,
                        31.96
                      ],
                      "crs": {
                        "code": "EPSG:4326",
                        "name": "WGS 84",
                        "source": "file",
                        "datum_shift": null,
                        "max_offset_ft": 0,
                        "alternatives": []
                      },
                      "name_field": "name",
                      "file": {
                        "name": "units.geojson",
                        "bytes": 1204,
                        "sha256": "9f2c4e1a7b3d5f6081a2c4e6b8d0f1a3c5e7092b4d6f8a1c3e5079b2d4f6a8c1"
                      },
                      "visibility": "tenant",
                      "created_by": "engineer@example.com",
                      "created_at": "2026-11-09T15:04:05.000Z",
                      "updated_at": "2026-11-09T15:04:05.000Z"
                    }
                  ],
                  "next_cursor": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "A server without a state store answers 409 \"Area sets need a state store; this server keeps plans in memory\".",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        }
      },
      "post": {
        "operationId": "createAreaSet",
        "tags": [
          "Design"
        ],
        "summary": "Keep areas by name",
        "description": "Keep the areas of a zipped shapefile, GeoJSON, KML or KMZ file by name. The file is read exactly as POST /areas reads it, against the request's model set; the answer is 201 with the set's record, its areas, skipped records and warnings, and its ETag.\n\n**Visibility.** `private` (the default) answers only its signed-in creator, so a request without a signed-in user must send `tenant` (else 400); `tenant` answers every user of the tenant.\n\n**Retries.** An `Idempotency-Key` replays the first answer under any model set: the set's current record, and its areas, skipped records and warnings as first answered. A replay of a set deleted since is 404.\n\n**Details.** `file` keeps the uploaded part's name, bytes and SHA-256 (null from a JSON body). Area sets aren't linked to plans: keep the set ids with a plan, as in its saved `views` document. A server without a state store answers 409 \"Area sets need a state store; this server keeps plans in memory\".",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "The file, its name and visibility: uploaded as multipart/form-data, or in a JSON body.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/AreaSetUpload"
              },
              "encoding": {
                "file": {
                  "contentType": "application/zip, application/geo+json, application/json, application/vnd.google-earth.kml+xml, application/vnd.google-earth.kmz"
                }
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAreaSetRequest"
              },
              "example": {
                "geojson": {
                  "type": "FeatureCollection",
                  "features": [
                    {
                      "type": "Feature",
                      "properties": {
                        "name": "Pecos Draw Unit",
                        "lease_no": "PD-17",
                        "gross_acres": 1280
                      },
                      "geometry": {
                        "type": "Polygon",
                        "coordinates": [
                          [
                            [
                              -101.95,
                              31.93
                            ],
                            [
                              -101.93,
                              31.93
                            ],
                            [
                              -101.93,
                              31.96
                            ],
                            [
                              -101.95,
                              31.96
                            ],
                            [
                              -101.95,
                              31.93
                            ]
                          ],
                          [
                            [
                              -101.945,
                              31.94
                            ],
                            [
                              -101.94,
                              31.94
                            ],
                            [
                              -101.94,
                              31.945
                            ],
                            [
                              -101.945,
                              31.945
                            ],
                            [
                              -101.945,
                              31.94
                            ]
                          ]
                        ]
                      }
                    }
                  ]
                },
                "name": "Lease outlines",
                "visibility": "tenant"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The set's record, its areas as read, and its ETag.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/VersionETag"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AreaSet"
                },
                "example": {
                  "id": "7d1f3c2a-5b4e-4f6a-9c8d-2e1b0a9f8e7d",
                  "name": "Lease outlines",
                  "count": 1,
                  "acres": 1490.74,
                  "bbox": [
                    -101.95,
                    31.93,
                    -101.93,
                    31.96
                  ],
                  "crs": {
                    "code": "EPSG:4326",
                    "name": "WGS 84",
                    "source": "file",
                    "datum_shift": null,
                    "max_offset_ft": 0,
                    "alternatives": []
                  },
                  "name_field": "name",
                  "file": {
                    "name": "units.geojson",
                    "bytes": 1204,
                    "sha256": "9f2c4e1a7b3d5f6081a2c4e6b8d0f1a3c5e7092b4d6f8a1c3e5079b2d4f6a8c1"
                  },
                  "visibility": "tenant",
                  "created_by": "engineer@example.com",
                  "created_at": "2026-11-09T15:04:05.000Z",
                  "updated_at": "2026-11-09T15:04:05.000Z",
                  "areas": [
                    {
                      "id": 0,
                      "name": "Pecos Draw Unit",
                      "properties": {
                        "name": "Pecos Draw Unit",
                        "lease_no": "PD-17",
                        "gross_acres": 1280
                      },
                      "geometry": {
                        "type": "Polygon",
                        "coordinates": [
                          [
                            [
                              -101.95,
                              31.93
                            ],
                            [
                              -101.93,
                              31.93
                            ],
                            [
                              -101.93,
                              31.96
                            ],
                            [
                              -101.95,
                              31.96
                            ],
                            [
                              -101.95,
                              31.93
                            ]
                          ],
                          [
                            [
                              -101.945,
                              31.945
                            ],
                            [
                              -101.94,
                              31.945
                            ],
                            [
                              -101.94,
                              31.94
                            ],
                            [
                              -101.945,
                              31.94
                            ],
                            [
                              -101.945,
                              31.945
                            ]
                          ]
                        ]
                      },
                      "acres": 1490.74,
                      "long_axis_azimuth_deg": 0,
                      "parts": 1,
                      "holes": 1,
                      "vertices": 8,
                      "in_dataset": true,
                      "fill": {
                        "polygon": [
                          [
                            -101.95,
                            31.93
                          ],
                          [
                            -101.93,
                            31.93
                          ],
                          [
                            -101.93,
                            31.96
                          ],
                          [
                            -101.95,
                            31.96
                          ]
                        ],
                        "simplified_from": null,
                        "max_deviation_ft": 0,
                        "dropped_parts": 0,
                        "dropped_holes": 1
                      }
                    }
                  ],
                  "skipped": [],
                  "warnings": [
                    "1 area has holes or several parts. A layout uses the largest part and keeps wells out of its holes."
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The Idempotency-Key was already used with another request; or, with Redis, the first request with this Idempotency-Key is still being made (after a 30 s wait); retry shortly with the same key. A server without a state store answers 409 \"Area sets need a state store; this server keeps plans in memory\".",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "description": "A model worker or the subsurface grids aren't ready, or, with Redis, the Redis that keeps Idempotency-Key records isn't answering; retry shortly with the same key.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unavailable",
                    "message": "The spacing model worker isn't running; retry shortly, and ask your Novi admin if it persists",
                    "details": {
                      "worker": "spacing"
                    }
                  },
                  "request_id": "0b5e8f2a-7c1d-4e6b-a3f9-5d2c8e4b1a70"
                }
              }
            }
          }
        }
      }
    },
    "/area-sets/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Area set id from POST /area-sets or GET /area-sets.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "getAreaSet",
        "tags": [
          "Design"
        ],
        "summary": "Get an area set",
        "description": "An area set's record and its areas, each as POST /areas gave it, and the set's ETag.\n\n**Model set.** `in_dataset`, and POST /areas' warning when an area lies outside, are worked out against this request's model set (GET /dataset bbox); `skipped` is empty.\n\n**Errors.** A private set answers only its signed-in creator; another user's private set, a deleted one, another tenant's or an unknown id is 404. A server without a state store answers 409 \"Area sets need a state store; this server keeps plans in memory\".",
        "responses": {
          "200": {
            "description": "The area set.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/VersionETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AreaSet"
                },
                "example": {
                  "id": "7d1f3c2a-5b4e-4f6a-9c8d-2e1b0a9f8e7d",
                  "name": "Lease outlines",
                  "count": 1,
                  "acres": 1490.74,
                  "bbox": [
                    -101.95,
                    31.93,
                    -101.93,
                    31.96
                  ],
                  "crs": {
                    "code": "EPSG:4326",
                    "name": "WGS 84",
                    "source": "file",
                    "datum_shift": null,
                    "max_offset_ft": 0,
                    "alternatives": []
                  },
                  "name_field": "name",
                  "file": {
                    "name": "units.geojson",
                    "bytes": 1204,
                    "sha256": "9f2c4e1a7b3d5f6081a2c4e6b8d0f1a3c5e7092b4d6f8a1c3e5079b2d4f6a8c1"
                  },
                  "visibility": "tenant",
                  "created_by": "engineer@example.com",
                  "created_at": "2026-11-09T15:04:05.000Z",
                  "updated_at": "2026-11-09T15:04:05.000Z",
                  "areas": [
                    {
                      "id": 0,
                      "name": "Pecos Draw Unit",
                      "properties": {
                        "name": "Pecos Draw Unit",
                        "lease_no": "PD-17",
                        "gross_acres": 1280
                      },
                      "geometry": {
                        "type": "Polygon",
                        "coordinates": [
                          [
                            [
                              -101.95,
                              31.93
                            ],
                            [
                              -101.93,
                              31.93
                            ],
                            [
                              -101.93,
                              31.96
                            ],
                            [
                              -101.95,
                              31.96
                            ],
                            [
                              -101.95,
                              31.93
                            ]
                          ],
                          [
                            [
                              -101.945,
                              31.945
                            ],
                            [
                              -101.94,
                              31.945
                            ],
                            [
                              -101.94,
                              31.94
                            ],
                            [
                              -101.945,
                              31.94
                            ],
                            [
                              -101.945,
                              31.945
                            ]
                          ]
                        ]
                      },
                      "acres": 1490.74,
                      "long_axis_azimuth_deg": 0,
                      "parts": 1,
                      "holes": 1,
                      "vertices": 8,
                      "in_dataset": true,
                      "fill": {
                        "polygon": [
                          [
                            -101.95,
                            31.93
                          ],
                          [
                            -101.93,
                            31.93
                          ],
                          [
                            -101.93,
                            31.96
                          ],
                          [
                            -101.95,
                            31.96
                          ]
                        ],
                        "simplified_from": null,
                        "max_deviation_ft": 0,
                        "dropped_parts": 0,
                        "dropped_holes": 1
                      }
                    }
                  ],
                  "skipped": [],
                  "warnings": []
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A server without a state store answers 409 \"Area sets need a state store; this server keeps plans in memory\".",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      },
      "patch": {
        "operationId": "updateAreaSet",
        "tags": [
          "Design"
        ],
        "summary": "Rename or share an area set",
        "description": "Change an area set's `name` or `visibility` (at least one) and get back its record and new ETag. Only its creator, signed in, can make it private.\n\n**Conflicts.** A stale `If-Match` is a 409 with the current ETag in `details.etag`, as is, with or without it, a change made while the request ran.\n\n**Errors.** A private set answers only its signed-in creator; another user's private set, a deleted one, another tenant's or an unknown id is 404. A server without a state store answers 409 \"Area sets need a state store; this server keeps plans in memory\".",
        "parameters": [
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The set's ETag, including quotes.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "The fields to change.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AreaSetPatch"
              },
              "example": {
                "name": "Lease outlines 2027",
                "visibility": "tenant"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated record and its ETag.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/VersionETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AreaSetMeta"
                },
                "example": {
                  "id": "7d1f3c2a-5b4e-4f6a-9c8d-2e1b0a9f8e7d",
                  "name": "Lease outlines",
                  "count": 1,
                  "acres": 1490.74,
                  "bbox": [
                    -101.95,
                    31.93,
                    -101.93,
                    31.96
                  ],
                  "crs": {
                    "code": "EPSG:4326",
                    "name": "WGS 84",
                    "source": "file",
                    "datum_shift": null,
                    "max_offset_ft": 0,
                    "alternatives": []
                  },
                  "name_field": "name",
                  "file": {
                    "name": "units.geojson",
                    "bytes": 1204,
                    "sha256": "9f2c4e1a7b3d5f6081a2c4e6b8d0f1a3c5e7092b4d6f8a1c3e5079b2d4f6a8c1"
                  },
                  "visibility": "tenant",
                  "created_by": "engineer@example.com",
                  "created_at": "2026-11-09T15:04:05.000Z",
                  "updated_at": "2026-11-09T15:04:05.000Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A stale If-Match, or a change made while the request ran (`details.etag` is the current one). A server without a state store answers 409 \"Area sets need a state store; this server keeps plans in memory\".",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        }
      },
      "delete": {
        "operationId": "deleteAreaSet",
        "tags": [
          "Design"
        ],
        "summary": "Delete an area set",
        "description": "Delete an area set and its areas. Anyone who can read it can delete it. A private set answers only its signed-in creator; another user's private set, a deleted one, another tenant's or an unknown id is 404. A server without a state store answers 409 \"Area sets need a state store; this server keeps plans in memory\".",
        "responses": {
          "204": {
            "description": "Deleted.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A server without a state store answers 409 \"Area sets need a state store; this server keeps plans in memory\".",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        },
        "parameters": []
      }
    },
    "/inventories/columns": {
      "get": {
        "operationId": "listInventoryColumns",
        "tags": [
          "Design"
        ],
        "summary": "List the inventory upload's columns",
        "description": "The upload's column catalog, in template order: each column's key, reader roles, headers and units, shapefile field, whether it is required, the request flag it needs and its aliases (see InventoryColumn). It doesn't depend on `model_set` and changes only with a deploy.\n\n**Shapefile units.** A shapefile's field names carry no unit: TVD, LATERALLEN and STAGE_LEN read as POST /inventories/read's units text says, FLUIDPERFT, PROPPERFT and FRAC_BPM in bbl/ft, lb/ft and bbl/min, and CLUST_STG as a count.\n\n**Template.** GET /inventories/template writes these headers as one line (Stage Length, Clusters per Stage and Frac Rate only where the model set's models read them); fill one well per row and send it to POST /inventories/read. The read needs `eur_water: true` for the water decline columns, `til_from_dates` for the drill and completion dates, and `designs_from_rows: true` for completion names.",
        "responses": {
          "200": {
            "description": "The inventory column catalog.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryColumnsResponse"
                },
                "example": {
                  "columns": [
                    {
                      "key": "name",
                      "roles": [
                        "name"
                      ],
                      "header": "Well Name",
                      "headers": {
                        "imperial": "Well Name",
                        "metric": "Well Name"
                      },
                      "field": "NAME",
                      "unit": null,
                      "required": "no",
                      "reads_with": null,
                      "description": "The well name, kept in rows and in wells with well_names: true.",
                      "aliases": [
                        "noviwellname",
                        "wellname",
                        "name",
                        "well",
                        "uniqueid",
                        "api10",
                        "uwi",
                        "api14",
                        "api12",
                        "chosenid"
                      ]
                    },
                    {
                      "key": "tvd_ft",
                      "roles": [
                        "tvd_ft"
                      ],
                      "header": "TVD (ft)",
                      "headers": {
                        "imperial": "TVD (ft)",
                        "metric": "TVD (m)"
                      },
                      "field": "TVD",
                      "unit": {
                        "imperial": "ft",
                        "metric": "m"
                      },
                      "required": "no",
                      "reads_with": null,
                      "description": "The true vertical depth in ft (imperial) or m (metric).",
                      "aliases": [
                        "novitvd",
                        "tvd",
                        "tvdft"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        },
        "parameters": []
      }
    },
    "/inventories/template": {
      "get": {
        "operationId": "getInventoryTemplate",
        "tags": [
          "Design"
        ],
        "summary": "Download an inventory template",
        "description": "Download one CSV header line, in GET /inventories/columns catalog order, to fill with one well per row and upload with POST /inventories/read. Stage Length, Clusters per Stage and Frac Rate appear only where the model set's models read them.\n\n**Units.** `units=imperial` (the default) writes ft, bbl/ft, lb/ft and bbl/min headers, as inventory-template.csv; `units=metric` writes m, m3/m, t/m and m3/min headers, as inventory-template-metric.csv. Any other or repeated value is a 400 on units. POST /inventories/read says how it reads headers and units.\n\n**Filling it.** Delete both Top Hole columns when no well has a surface hole: a row with blank Top Hole cells reads with an issue, taking the heel as shl. The read needs `eur_water: true`, `til_from_dates` and `designs_from_rows: true` for the water decline columns, the drill and completion dates and the completion names.",
        "parameters": [
          {
            "name": "units",
            "in": "query",
            "description": "The header units: units=imperial or units=metric; send once.",
            "schema": {
              "type": "string",
              "enum": [
                "imperial",
                "metric"
              ],
              "default": "imperial"
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "One CSV header line.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Content-Disposition": {
                "description": "attachment; filename=\"inventory-template.csv\", or \"inventory-template-metric.csv\" with units=metric.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/inventories/write": {
      "post": {
        "operationId": "writeInventory",
        "tags": [
          "Design"
        ],
        "summary": "Download a plan's wells as an inventory file",
        "description": "Write the sent wells as an inventory file, CSV (default), GeoJSON or a zipped shapefile, that POST /inventories/read reads back. Formation names are checked against the selected dataset; nothing is stored.\n\n**Formats.** One of three:\n\n- CSV: UTF-8 without a BOM, comma-separated, quoted where needed, LF line ends and a final newline. A text cell starting with =, +, -, @, a tab or a carriage return (after any apostrophes) gets a leading apostrophe against spreadsheet formulas; the read takes it off.\n- GeoJSON: a WGS 84 FeatureCollection of two-point LineStrings with no crs member; properties hold the other columns, numbers as numbers, blanks as null.\n- Shapefile: a zip of a PolyLine .shp, .shx, dBASE III .dbf, WGS 84 .prj and UTF-8 .cpg. Numeric attributes are fixed-decimal, at most 19 characters and 15 decimals, so a value with more decimals is rounded.\n\n**Columns.** In GET /inventories/columns catalog order, only those some well has.\n\n- CSV and GeoJSON headers use the chosen units (metric: m, m3/m, t/m and m3/min). Shapefile attributes take the catalog's field names, plus UNITS, always in ft, bbl/ft, lb/ft and bbl/min.\n- Heelpoint is heel, else shl; Bottom Hole is bhl. CSV Top Hole columns appear only when some well has heel, holding shl for those wells and blank for the others. Lines run from heel (else shl) to bhl.\n- The stated lateral is typed_lateral.length_ft only while the model would take it: its ends match heel (else shl) and bhl exactly, and it is within 5% of their measured length or within 100 to 50,000 ft.\n- landing_below_top_ft, landing_fraction, lateral_length_ft, lateral_outside, part and bench aren't written. Names and scenarios are trimmed, formation takes the dataset's canonical name, and pads are text.\n- A well's flat decline settings (decline.b_min, b_max, terminal_decline) fill each stream's unset columns; water's only when the well sets decline.water or the request sends eur_water: true.\n\n**Reading it back.** POST /inventories/read of the CSV with well_names: true (and eur_water: true when a well sets decline.water or the write sent it) returns the wells as written: the fields above, decline settings per stream, stage length, clusters per stage and frac rate (a null reads back absent), and a metric file's values to the read's 1e-6 rounding. GeoJSON and shapefile read back likewise, a shapefile's numbers to its 15 decimals, except that a line holds no separate surface hole: shl is its start and heel is absent. A shapefile's UNITS is always ft, whatever its units says. A well with neither end in GET /dataset's bbox is written, and the read leaves it out.\n\n**Refused (400).** Each names the field it is on.\n\n- Fewer than 1 or more than GET /dataset limits.plan_wells wells (on wells, with details.max and details.count above the cap).\n- An invalid well or pad, or a well without formation, which the read would leave out.\n- A stream whose b_min isn't below its b_max, an unset one counting as 0.5 or 2.5.\n- A shapefile whose fixed decimals would round a value to one the read drops (on that field or decline.<stream>, suggesting CSV or GeoJSON):\n  - a tvd_ft, fluid_bbl_per_ft, proppant_lb_per_ft, stage_length_ft, clusters_per_stage or frac_rate_bbl_per_min not over 0 and under its maximum, or a b_min not below its b_max.\n- Two wells with the same Heelpoint and Bottom Hole (and Top Hole, in a CSV) to 1e-6°, the same name or none and the same scenario or none, which the read would take as one (on the second's name, with details.wells giving both indexes).\n- A shapefile whose .shp, .shx or .dbf would pass 32 MB, or all of them 64 MB, the most the read takes (on format; write CSV or GeoJSON).\n- An invalid format, units or name, or unknown body fields.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InventoryWriteRequest"
              },
              "example": {
                "wells": [
                  {
                    "name": "Inventory 1H",
                    "shl": [
                      -101.93,
                      31.93
                    ],
                    "bhl": [
                      -101.93,
                      31.957
                    ],
                    "formation": "WOLFCAMP A",
                    "tvd_ft": 9000
                  },
                  {
                    "name": "Inventory 2H",
                    "shl": [
                      -101.928,
                      31.93
                    ],
                    "bhl": [
                      -101.928,
                      31.957
                    ],
                    "formation": "WOLFCAMP A",
                    "pad": 7
                  }
                ],
                "format": "csv",
                "units": "imperial",
                "name": "inventory"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The inventory file.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Content-Disposition": {
                "description": "attachment; filename=\"<name>.csv\", \"<name>.geojson\" or \"<name>.zip\".",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/geo+json": {
                "schema": {
                  "type": "object",
                  "description": "A GeoJSON FeatureCollection: one two-point LineString per well, its columns as properties."
                },
                "example": {
                  "type": "FeatureCollection",
                  "features": [
                    {
                      "type": "Feature",
                      "geometry": {
                        "type": "LineString",
                        "coordinates": [
                          [
                            -101.93,
                            31.93
                          ],
                          [
                            -101.93,
                            31.957
                          ]
                        ]
                      },
                      "properties": {
                        "Well Name": "Inventory 1H",
                        "Pad Name": null,
                        "Target Formation": "WOLFCAMP A",
                        "TVD (ft)": 9000
                      }
                    },
                    {
                      "type": "Feature",
                      "geometry": {
                        "type": "LineString",
                        "coordinates": [
                          [
                            -101.928,
                            31.93
                          ],
                          [
                            -101.928,
                            31.957
                          ]
                        ]
                      },
                      "properties": {
                        "Well Name": "Inventory 2H",
                        "Pad Name": "7",
                        "Target Formation": "WOLFCAMP A",
                        "TVD (ft)": null
                      }
                    }
                  ]
                }
              },
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "description": "The request body is over 64 MB.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/inventories/read": {
      "post": {
        "operationId": "readInventory",
        "tags": [
          "Design"
        ],
        "summary": "Read planned wells from a file",
        "description": "Planned wells from a file, as the `wells` POST /forecasts and POST /plans take, with what became of each row. Nothing is stored: send the file again to read it again.\n\n**Upload.** Send the file as `multipart/form-data`, a `file` part and each option as its own part, as `curl -F file=@wells.csv -F formation=\"WOLFCAMP A\" <origin>/api/v1/inventories/read`. Clients limited to JSON, such as MCP tools, send `csv` (the text), `geojson` or `shapefile` (the zip in base64) in a JSON body instead; the answer is the same. A zip holding `[Content_Types].xml` is a workbook and any other zip a line shapefile; a JSON object with a `type` is GeoJSON; anything else is a CSV. An .xls is a 400: save it as .xlsx or CSV.\n\n**The wells.** `wells` post as they are to POST /forecasts (up to 50) or POST /plans, each with the fields its row read cleanly (see `wells`). Positions are WGS 84 degrees, as the file has them when they needed no shift or projection, else rounded to 1e-7°.\n\n- Wells with `decline` need `\"eur\": true`, and wells read with `eur_water: true` need `\"eur_water\": true` too, or the request is a 400.\n- A well with no `tvd_ft` that POST /tvd-estimates can't estimate fails the request it is posted in (a plan with `per_well_errors: true`, only that well), so give it one.\n- Names stay in `rows` (`wells[k]` is the row whose `well` is k), unless `well_names: true` puts them on the wells.\n\n**Rows.** Every row is in `rows`, in file order, with its `issues` and `well`, its index in `wells` or null. A file whose rows all fail is a 200 with `count: 0`. A row is left out for:\n\n- a blank or unreadable position, or a lateral outside 100 to 50,000 ft;\n- no end in the dataset's bbox, so its TVD couldn't be estimated;\n- no formation, or one this dataset lacks;\n- repeating an earlier well: the same name, the same ends (and heel, when read) to 1e-6° and the same inventory name (\"same well as row k\"; the first row's values stand). The same name at other ends is kept, with an issue.\n\nA TVD outside 0 to 40,000 ft (exclusive) is dropped with an issue and estimated instead. A TIL date not in one of the three date forms (YYYY-MM-DD, YYYY/M/D, YYYYMMDD), or outside the dataset's as_of to 30 years from today, is dropped with an issue, and the well takes the next wider layer's date. A kept TVD more than 50 ft above its formation's top or below its base at the well, where the set's grids give both (as `landing_fraction` measures them), stays, with an issue saying by how much.\n\n**Lateral lengths.** A stated lateral length is the well's `typed_lateral`, which the model takes in place of the drawn length when it is within 5% of it or within 100 to 50,000 ft. One more than 5% off gets an issue saying the model takes it, which catches a surface hole read as the heel and lengths in metres; one also outside 100 to 50,000 ft is ignored, with an issue.\n\n**CSV.** As Novi's earlier Forecast Engine takes inventory and forecast input uploads, and as Novi's inventory exports write them: RFC 4180, comma- or tab-separated by whichever the header line has more of, UTF-8 else Windows-1252, a leading BOM dropped. The first non-blank line is the header; rows are numbered from 0 after it, blank lines left out, and a row with more or fewer cells than the header is left out.\n\nPositions are latitude and longitude in decimal degrees (as 31.93 or -1.2e2), WGS 84 unless `crs` says otherwise. One out of range leaves its row out, with a hint that the two may be swapped. A name, formation, inventory name or pad cell that starts with an apostrophe before =, +, -, @, a tab or a carriage return (or more apostrophes, then one of those) loses one apostrophe, undoing POST /inventories/write's spreadsheet quoting.\n\n**Workbooks.** A sheet reads as a CSV does (`format: xlsx`), from each cell's stored value: number formats aren't applied, so a number shown as 00123 reads 123. A row that ends before the header's last column reads the rest as blank. Dates are read from their serials in the workbook's date system (1900 or 1904), the time of day dropped.\n\n`sheet` picks a workbook's sheet by name (exact, else in any case) or index from 0, else the first, with a warning when there are more; one the workbook lacks is a 400 with `details.sheets`. A name of digits only reads as an index, so pick a sheet by its position in `sheets` (`include` `[\"sheets\"]`), where a name over 31 characters is cut to 31 and ends in ….\n\n**Lines.** A GeoJSON FeatureCollection, Feature, LineString or MultiLineString, or a zip's first PolyLine (Z or M) layer (a warning names the others), as Intelligence's map export gives them. A line runs from its heel, the first vertex of its first part, to its toe, the last vertex of its last part: its well's `shl` is the line's start, with no `heel`. The vertices between are dropped, and a line of several parts gets an issue. Other geometries, null shapes and deleted records are rows left out; a shapefile's records past its .dbf's last row aren't read, with a warning. The coordinate system is found as POST /areas finds it.\n\n**Columns.** Each role reads the first of its names the file has, compared lowercased with all but letters and digits dropped (Heelpoint Latitude is heelpointlatitude), or the column `columns` names:\n\n- `name`: noviwellname, wellname, name, well, uniqueid, api10, uwi, api14, api12, chosenid\n- `formation`: noviformation, targetformation, formation, targetzone, landingzone, zone\n- `tvd_ft`: novitvd, tvd, tvdft\n- `til_date`: novitildate, tildate, til\n- `lateral_length_ft`: novilaterallength, laterallength, laterallen\n\nThe answer's `columns` holds an optional role only when the file has it.\n\n**Completion columns.** Read into each well whether or not the model set's models read them:\n\n- `fluid_bbl_per_ft`: novicalcfluidperlength, fluidbblperft, fluidperft, fluidperlength\n- `proppant_lb_per_ft`: novicalcproppantperlength, proppantlbperft, proppantperft, proppantperlength, propperft\n- `stage_length_ft`: novistagelength, novicalcstagespacing, stagelengthft, stagelength, stagespacing, stagespacingft, stagelen\n- `clusters_per_stage`: noviclustersperstage, novicalcclustersperstage, clustersperstage, cluststg\n- `frac_rate_bbl_per_min`: novifracrate, fracratebblpermin, fracrate, fracratebblmin, fracratebpm, fracbpm\n\nA blank cell leaves the well to the request's completions. A value out of range (fluid over 0 and under 1,000 bbl/ft, proppant over 0 and under 20,000 lb/ft, stage length over 0 and under 2,000 ft, clusters per stage over 0 and under 100, frac rate over 0 and under 500 bbl/min) is dropped with an issue. A warning names filled stage columns the model set's models don't read.\n\n**Scenario and pad columns.**\n\n- `scenario`: wellinventoryname, inventoryname, scenario, wellinven. The inventory's name; one over 60 characters is dropped with an issue.\n- `pad`: novipadname, padname, pad, novipadn. Text, read as `scenario` is; see WellInput `pad`.\n\nA warning says when only some wells have an inventory name, since a plan takes a scenario on every well or none, and when the file names more than 20.\n\n**Decline columns.** A discrete forecast input file's EUR settings, read into each well's `decline`:\n\n- `eur_years`: euryears\n- oil: `oil_min_b` oilminb, `oil_max_b` oilmaxb, `oil_terminal_decline` oilterminaldecline, oiltermin\n- gas: `gas_min_b` gasminb, `gas_max_b` gasmaxb, `gas_terminal_decline` gasterminaldecline, gastermin\n- water, into `decline.water`, only with `eur_water: true`: `water_min_b` waterminb, watermin, `water_max_b` watermaxb, watermax, `water_terminal_decline` waterterminaldecline, waterterm\n\nA blank cell leaves the well to the request's settings. A value outside the API's bounds is dropped with an issue (those files' terminal decline can run past 0.01 to 0.2), and a min b at or above its row's max b drops both. On a model set whose oil slot holds condensate, `condensate_min_b`, `condensate_max_b` and `condensate_terminal_decline` fill the oil roles in place of oil's names when the file has any of them. On a set that doesn't serve oil or gas, that stream's names aren't looked for, but a role named in `columns` or `column_hints` reads. A warning names decline columns no role reads.\n\n**Positions.** A CSV's ends; a line's are its vertices.\n\n- The heel: noviheellatitude, heelpointlatitude, heellatitude, heellat, lplatitude, each with longitude, lng or lon for the longitude.\n- The surface hole: novisurfaceholelatitude, surfaceholelatitude, topholelatitude, shllatitude, shllat.\n- The bottom hole: novibottomholelatitude, bottomholelatitude, bhllatitude, bhllat, toelatitude, toelat.\n\n`shl` reads the heel when the file has its latitude and longitude, else the surface hole, with a warning. A file with both reads both: `shl` is the surface hole and `heel` the heel, unless a row's surface hole is blank, unreadable or more than 50,000 ft from its heel (dropped with an issue; the heel goes in `shl`). From a file with only a surface hole, laterals start there, and the length check flags it when the file states lengths.\n\nIn `columns`, name an end's latitude and longitude together (`shl_lat` and `shl_lng`, `heel_lat` and `heel_lng`, `bhl_lat` and `bhl_lng`; a 400 on one left out). A named heel pairs with a surface hole as a found one does; naming `shl_lat` and `shl_lng` without the heel's reads no heel. A CSV without both ends' columns is a 400.\n\n**Column hints.** `column_hints` names columns to try for a role `columns` and the names above leave unread: 1 to 20 names per role, each 1 to 200 characters, compared as the names above, a name the file lacks skipped, so one team's hints serve every file. Teams keep them in the saved collection `column-mappings`. A CSV's end (`shl`, `heel` or `bhl`) takes its hinted latitude and longitude only when both are found and the file has no columns for that end by name (for `shl`, neither the heel's nor the surface hole's) or in `columns` (for `heel`, nor a named `shl`); the end then reads as if named in `columns`.\n\n**Units.** `units` is the file's system. Values are converted to ft, bbl/ft, lb/ft and bbl/min before they are checked, so every bound and the 5% check hold in those units, and `wells` are always in them. An issue on a converted value quotes the file's value and unit, then the converted one. Clusters per stage have no unit.\n\n- A header ending in a unit in parentheses or brackets, as `TVD (m)` or `Fluid per Length [m3/m]`, is in that unit whatever `units` says, and so is a column whose name says ft, bbl/ft, lb/ft or bbl/min.\n- Those names: tvdft, fluidbblperft, fluidperft, proppantlbperft, proppantperft, propperft, stagelengthft, stagespacingft, fracratebblpermin, fracratebblmin, fracratebpm, fracbpm.\n- For TVD, lateral length, fluid, proppant, stage length and frac rate, a header that matches no name whole is matched by the name before its unit: `Lateral Length (ft)` reads as `lateral_length_ft`. Other bracketed headers, as `Zone (ft)`, are matched whole.\n- Header units, in any case (³ or 3): length ft, feet, foot, m, metre, metres, meter, meters; fluid per length bbl/ft, bbls/ft, gal/ft, gals/ft, m3/m; proppant per length lb/ft, lbs/ft, kg/m, t/m, tonne/m, tonnes/m; fluid per minute bbl/min, bbls/min, bpm, m3/min.\n- A header naming a unit of another kind, as `TVD (bbl/ft)`, is read in the request's units with a warning.\n\nA shapefile whose records all carry a `UNITS` attribute of exactly `ft`, or all exactly `m`, is read in that system whatever `units` says (with a warning when `units` names the other), as POST /inventories/write marks them; a header's unit still wins. When some records say `ft` or `m` but not every record says the same, `UNITS` is ignored with a warning; when none says either, without one. The answer's `units` gives the `system` and each role's `unit` and where it came `from`.\n\n**Formations.** A row's formation maps through `formations` (up to 100 of the file's names), then matches GET /formations in any case and comes back as it names it; a blank takes the request's `formation` (a 400 when GET /formations lacks it). A mapping value that isn't a name is a 400 on `formations.<name>`. `unknown_formations` lists the names that matched nothing: map them in `formations` and send the file again.\n\n**Dates.** With `til_from_dates` (even `{}`), the `drill_date` (novidrillingdate, novispuddate, drilldate, drillingdate, spuddate, novispud) and `completion_date` (novifracdate, completiondate, fracdate, compldate, novifrac) columns are read in the three date forms. A well whose TIL date is blank, unreadable or dropped takes its completion date plus `completion_to_til_days`, else its drill date plus `drill_to_completion_days` and `completion_to_til_days`: whole days from 0 to 365, 42 each by default.\n\nA derived date is checked as a TIL date is, and dropped with an issue naming the date it came from; `rows[].til_from` says where each kept well's date came from, and a warning counts the wells that took one. Unreadable dates, a drill date after the completion date and a completion date after the kept TIL date are issues. Without the option these columns aren't read, and naming them in `columns` is a 400.\n\n**Several rows per well.** With `designs_from_rows: true`, a row that repeats a well (the key under Rows) with a completion the well doesn't have yet is that well under another design, so a file listing each well once per completion reads as its wells under the file's designs. A completion is its `completion_name` (novicompletionname, completionname, designname, design; text, a name over 60 characters dropped with an issue) when filled, else its fluid, proppant and the stage inputs the model set's models read. A stage input the models don't read is the completion's first row's.\n\nWhen some well has rows of two completions, the answer adds `designs`, one per completion in first-seen order, and each kept row's `design`, its index there; its `wells` carry no completions. A design is named by its `completion_name`, else `<proppant> lb/ft · <fluid> bbl/ft` (`default` for a blank value), then ` · <v> ft`, ` · <v>/stage` and ` · <v> bbl/min` for its stage inputs, or ` · #<n>` when that would pass 60 characters.\n\nSend `wells` and `designs` to POST /plans as they are; warnings count the forecasts (wells × designs) and say when they pass GET /dataset `limits.plan_wells`. A row whose completion name an earlier row set with other values is left out, naming that row, and so are the rows of the 11th completion on (a plan takes 10 designs), with a warning.\n\n**Limits.**\n\n- The 64 MB request body.\n- GET /dataset `limits.plan_wells` rows, a 400 with `details.max` and `details.count` (split the file); a CSV is read only to the first row past it, so its `details.count` is `details.max` + 1.\n- A CSV header of 500 columns, cells cut at 200 characters.\n- A workbook of 1,000 zip entries, 32 MB for each part it reads and 64 MB in all, 1,000,000 shared strings, 2,000,000 cells with a value and 500 columns, and a fixed amount of reading work (a 400 with `details.max_work`).\n- A GeoJSON file's first 500 property names (a `columns` name past them is a 400); a zip as POST /areas reads one; for lines, a fixed amount of reading and projection work (a 400 \"too complex\").\n\n**Errors.** 400 with `details.field` naming the input: `csv`, `geojson`, `shapefile` or `file` for the file (unreadable, empty, no line layer, too many rows), `sheet`, `crs` (with `details.supported`), `formation`, `formations` or `formations.<name>`, `columns.<role>`, `include` and `include[0]` (an unknown value, with `details.allowed`), `body`, or an unknown multipart part's name. A body over 64 MB is a 413.",
        "requestBody": {
          "required": true,
          "description": "The file: uploaded as multipart/form-data, or in a JSON body for clients limited to JSON.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/InventoryUpload"
              },
              "encoding": {
                "file": {
                  "contentType": "text/csv, text/tab-separated-values, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/zip, application/geo+json, application/json"
                }
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InventoryRequest"
              },
              "examples": {
                "csv": {
                  "summary": "A planned well inventory CSV",
                  "value": {
                    "csv": "Well Name,Pad Name,Target Formation,Lateral Length,Heelpoint Latitude,Heelpoint Longitude,Bottom Hole Latitude,Bottom Hole Longitude,Top Hole Latitude,Top Hole Longitude,TVD,TIL Date\nPecos Draw 1H,Pecos Draw,Wolfcamp A,10000,31.93,-101.95,31.9575,-101.95,31.9295,-101.9495,9450,2027-03-01\nPecos Draw 2H,Pecos Draw,Wolfcamp A,10000,31.93,-101.947,31.9575,-101.947,31.9295,-101.9475,,2027/3/1\nPecos Draw 3H,Pecos Draw,WFMP B,10000,31.93,-101.944,31.9575,-101.944,31.9295,-101.9455,,\nPecos Draw 4H,Pecos Draw,3rd Bone Spring,10000,31.93,-101.941,31.9575,-101.941,31.9295,-101.9435,,\n",
                    "formations": {
                      "WFMP B": "WOLFCAMP B"
                    }
                  }
                },
                "geojson": {
                  "summary": "GeoJSON well paths",
                  "value": {
                    "geojson": {
                      "type": "FeatureCollection",
                      "features": [
                        {
                          "type": "Feature",
                          "properties": {
                            "name": "Pecos Draw 5H",
                            "formation": "Lower Spraberry Shale",
                            "tvd": 8600
                          },
                          "geometry": {
                            "type": "LineString",
                            "coordinates": [
                              [
                                -101.938,
                                31.93
                              ],
                              [
                                -101.938,
                                31.94375
                              ],
                              [
                                -101.938,
                                31.9575
                              ]
                            ]
                          }
                        },
                        {
                          "type": "Feature",
                          "properties": {
                            "name": "Pecos Draw 6H",
                            "formation": null,
                            "tvd": null
                          },
                          "geometry": {
                            "type": "LineString",
                            "coordinates": [
                              [
                                -101.935,
                                31.93
                              ],
                              [
                                -101.935,
                                31.9575
                              ]
                            ]
                          }
                        }
                      ]
                    },
                    "formation": "WOLFCAMP A"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The wells, and every row in file order.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryResponse"
                },
                "example": {
                  "count": 3,
                  "format": "csv",
                  "crs": {
                    "code": "EPSG:4326",
                    "name": "WGS 84",
                    "source": "file",
                    "datum_shift": null,
                    "max_offset_ft": 0,
                    "alternatives": []
                  },
                  "columns": {
                    "name": "Well Name",
                    "formation": "Target Formation",
                    "tvd_ft": "TVD",
                    "til_date": "TIL Date",
                    "lateral_length_ft": "Lateral Length",
                    "shl_lat": "Top Hole Latitude",
                    "shl_lng": "Top Hole Longitude",
                    "heel_lat": "Heelpoint Latitude",
                    "heel_lng": "Heelpoint Longitude",
                    "bhl_lat": "Bottom Hole Latitude",
                    "bhl_lng": "Bottom Hole Longitude",
                    "pad": "Pad Name"
                  },
                  "fields": [
                    "Well Name",
                    "Pad Name",
                    "Target Formation",
                    "Lateral Length",
                    "Heelpoint Latitude",
                    "Heelpoint Longitude",
                    "Bottom Hole Latitude",
                    "Bottom Hole Longitude",
                    "Top Hole Latitude",
                    "Top Hole Longitude",
                    "TVD",
                    "TIL Date"
                  ],
                  "wells": [
                    {
                      "shl": [
                        -101.9495,
                        31.9295
                      ],
                      "heel": [
                        -101.95,
                        31.93
                      ],
                      "bhl": [
                        -101.95,
                        31.9575
                      ],
                      "typed_lateral": {
                        "length_ft": 10000,
                        "heel": [
                          -101.95,
                          31.93
                        ],
                        "bhl": [
                          -101.95,
                          31.9575
                        ]
                      },
                      "formation": "WOLFCAMP A",
                      "tvd_ft": 9450,
                      "til_date": "2027-03-01",
                      "pad": "Pecos Draw"
                    },
                    {
                      "shl": [
                        -101.9475,
                        31.9295
                      ],
                      "heel": [
                        -101.947,
                        31.93
                      ],
                      "bhl": [
                        -101.947,
                        31.9575
                      ],
                      "typed_lateral": {
                        "length_ft": 10000,
                        "heel": [
                          -101.947,
                          31.93
                        ],
                        "bhl": [
                          -101.947,
                          31.9575
                        ]
                      },
                      "formation": "WOLFCAMP A",
                      "til_date": "2027-03-01",
                      "pad": "Pecos Draw"
                    },
                    {
                      "shl": [
                        -101.9455,
                        31.9295
                      ],
                      "heel": [
                        -101.944,
                        31.93
                      ],
                      "bhl": [
                        -101.944,
                        31.9575
                      ],
                      "typed_lateral": {
                        "length_ft": 10000,
                        "heel": [
                          -101.944,
                          31.93
                        ],
                        "bhl": [
                          -101.944,
                          31.9575
                        ]
                      },
                      "formation": "WOLFCAMP B",
                      "pad": "Pecos Draw"
                    }
                  ],
                  "rows": [
                    {
                      "id": 0,
                      "name": "Pecos Draw 1H",
                      "well": 0,
                      "lateral_length_ft": 10004,
                      "in_dataset": true,
                      "issues": [
                        "TVD 9,450 ft is 93 ft below WOLFCAMP A here (top 8,925 ft, base 9,357 ft); check the column holds TVD in the unit it names"
                      ]
                    },
                    {
                      "id": 1,
                      "name": "Pecos Draw 2H",
                      "well": 1,
                      "lateral_length_ft": 10004,
                      "in_dataset": true,
                      "issues": []
                    },
                    {
                      "id": 2,
                      "name": "Pecos Draw 3H",
                      "well": 2,
                      "lateral_length_ft": 10004,
                      "in_dataset": true,
                      "issues": []
                    },
                    {
                      "id": 3,
                      "name": "Pecos Draw 4H",
                      "well": null,
                      "lateral_length_ft": 10004,
                      "in_dataset": true,
                      "issues": [
                        "formation \"3rd Bone Spring\" isn't one of this dataset's; map it in formations (GET /formations lists them)"
                      ]
                    }
                  ],
                  "unknown_formations": [
                    {
                      "value": "3rd Bone Spring",
                      "rows": 1
                    }
                  ],
                  "warnings": [
                    "Left out 1 of 4 rows; rows[].issues says why.",
                    "1 well has issues (a value dropped, a name repeated at other ends, a stated length off the drawn one, or a TVD outside its formation); rows[].issues says which.",
                    "1 row names a formation this dataset lacks, listed in unknown_formations; map each to one of GET /formations in formations."
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "description": "The request body is over 64 MB.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/pads/read": {
      "post": {
        "operationId": "readPads",
        "tags": [
          "Design"
        ],
        "summary": "Read pads and their wells from a file of pad outlines",
        "description": "Pads from a file of pad outlines, each with the wells POST /layouts/fill lays in it, named by its pad and ready for POST /plans. Nothing is stored: send the file again to read it again.\n\n**Upload.** The file is read as POST /areas reads it, sent as `multipart/form-data` (`curl -F file=@pads.zip -F formation=\"WOLFCAMP A\" <origin>/api/v1/pads/read`) or in a JSON body, and the naming, `crs`, `fields`, `skipped` and warnings come as POST /areas gives them, without its warning on holes or several parts. Each polygon is a pad; points and lines are in `skipped`, with a warning when there are points.\n\n**The wells.** `wells` and `pad_values` post as they are to POST /plans: `{\"wells\": wells, \"pads\": pad_values}`. A pad's `pad_values` entry holds those of these the file gives (with none, it changes nothing in the plan); a value that doesn't read is dropped with an issue, keeping the pad:\n\n- TIL date, read as POST /inventories/read reads one, from GET /dataset `as_of` to 30 years from today;\n- fluid and proppant per ft, over 0 and under 1,000 bbl/ft and 20,000 lb/ft;\n- the stage inputs: stage length over 0 and under 2,000 ft, clusters per stage over 0 and under 100, frac rate over 0 and under 500 bbl/min;\n- TVD (over 0 and under 40,000 ft) or landing fraction (0 at the formation top to 1 at its base); with both, the TVD is kept, with an issue.\n\n**Columns.** Each role reads the first of its names the file has, found as POST /inventories/read finds them, or the field `columns` names (exactly, else in any case; an unknown role or field is a 400):\n\n- `formation`: noviformation, targetformation, formation, targetzone, landingzone, zone\n- `til_date`: novitildate, tildate, til\n- `lateral_length_ft`: novilaterallength, laterallength, laterallen\n- `tvd_ft`: novitvd, tvd, tvdft\n- `fluid_bbl_per_ft`: novicalcfluidperlength, fluidbblperft, fluidperft, fluidperlength\n- `proppant_lb_per_ft`: novicalcproppantperlength, proppantlbperft, proppantperft, proppantperlength, propperft\n- `wells_per_section`: wellspersection, wps\n- `spacing_ft`: spacingft, lateralspacing, spacing\n- `azimuth_deg`: azimuthdeg, azimuth, azi\n- `setback_ft`: setbackft, setback\n- `landing_fraction`: landingfraction\n- `stage_length_ft`: novistagelength, novicalcstagespacing, stagelengthft, stagelength, stagespacing, stagespacingft, stagelen\n- `clusters_per_stage`: noviclustersperstage, novicalcclustersperstage, clustersperstage, cluststg\n- `frac_rate_bbl_per_min`: novifracrate, fracratebblpermin, fracrate, fracratebblmin, fracratebpm, fracbpm\n\nA warning names filled stage fields the model set's models don't read, and a role field missing from a pad that carries POST /areas' 50 properties.\n\n**Laying out.** Each pad lays its wells as POST /layouts/fill does, in its `outline`, or its whole `area` when it has holes or several parts. It takes its `azimuth_deg` (else the outline's long axis), `lateral_length_ft` (else edge to edge), `setback_ft` (else 0) and one bench: its `formation` (any case; a blank one takes the request's) at its `wells_per_section` (1 to 52, whole), else a `spacing_ft` that is 5,280 ft over such a number (within 1e-6), else the request's `wells_per_section` (default 6).\n\nA value out of range (an azimuth outside -360 to 360, a lateral length outside 1,000 to 30,000 ft, a setback outside 0 to 2,640 ft, a spacing that isn't such a number, with the nearest one named) is dropped with an issue, and the pad takes the fallback.\n\n**Left out.** A pad left out has `left_out: true`, no wells and the reason last in `issues`:\n\n- a name over 60 characters, or one a pad kept before it has;\n- an outline that can't be filled, or outside the dataset (GET /dataset bbox);\n- a blank formation without the request's, or a formation the dataset lacks (counted in `unknown_formations`);\n- holes too detailed to check in one request (send fewer or simpler pads);\n- a fill POST /layouts/fill would refuse (its message), or no well laid.\n\n**Limits.** POST /areas' limits; GET /dataset `limits.plan_wells` wells in all; and 35,000,000 of fill work in all (35 times one POST /layouts/fill's), counting each pad that reaches its fill. Past one, a 400 on the file's field with `details.max` and `details.count` (polygons, wells) or `details.max_work` and `details.work`. Pads are laid in file order, and for the wells `details.count` is the wells laid up to the pad that passed the limit.\n\n**Errors.** 400 with `details.field` naming the input, as POST /areas' are, and `columns.<role>` (with `details.fields` for a field the file lacks), `formation` or `wells_per_section`. A body over 10 MB is a 413.",
        "requestBody": {
          "required": true,
          "description": "The file: uploaded as multipart/form-data, or in a JSON body for clients limited to JSON.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/PadsUpload"
              },
              "encoding": {
                "file": {
                  "contentType": "application/zip, application/geo+json, application/json, application/vnd.google-earth.kml+xml, application/vnd.google-earth.kmz"
                }
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PadsReadRequest"
              },
              "examples": {
                "geojson": {
                  "summary": "GeoJSON pad outlines",
                  "value": {
                    "geojson": {
                      "type": "FeatureCollection",
                      "features": [
                        {
                          "type": "Feature",
                          "properties": {
                            "pad_name": "North Pad",
                            "target_formation": "Wolfcamp A",
                            "wps": 4,
                            "til_date": "2027-03-01"
                          },
                          "geometry": {
                            "type": "Polygon",
                            "coordinates": [
                              [
                                [
                                  -101.95,
                                  31.93
                                ],
                                [
                                  -101.938,
                                  31.93
                                ],
                                [
                                  -101.938,
                                  31.957
                                ],
                                [
                                  -101.95,
                                  31.957
                                ],
                                [
                                  -101.95,
                                  31.93
                                ]
                              ]
                            ]
                          }
                        },
                        {
                          "type": "Feature",
                          "properties": {
                            "pad_name": "Middle Pad",
                            "target_formation": null,
                            "spacing": 1320,
                            "til_date": null
                          },
                          "geometry": {
                            "type": "Polygon",
                            "coordinates": [
                              [
                                [
                                  -101.93,
                                  31.93
                                ],
                                [
                                  -101.918,
                                  31.93
                                ],
                                [
                                  -101.918,
                                  31.957
                                ],
                                [
                                  -101.93,
                                  31.957
                                ],
                                [
                                  -101.93,
                                  31.93
                                ]
                              ]
                            ]
                          }
                        },
                        {
                          "type": "Feature",
                          "properties": {
                            "pad_name": "South Pad",
                            "target_formation": "Barnett",
                            "wps": 6,
                            "til_date": null
                          },
                          "geometry": {
                            "type": "Polygon",
                            "coordinates": [
                              [
                                [
                                  -101.95,
                                  31.9
                                ],
                                [
                                  -101.938,
                                  31.9
                                ],
                                [
                                  -101.938,
                                  31.92
                                ],
                                [
                                  -101.95,
                                  31.92
                                ],
                                [
                                  -101.95,
                                  31.9
                                ]
                              ]
                            ]
                          }
                        }
                      ]
                    },
                    "formation": "WOLFCAMP B"
                  }
                },
                "kml": {
                  "summary": "KML pad outlines",
                  "value": {
                    "kml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><kml xmlns=\"http://www.opengis.net/kml/2.2\"><Document><Placemark><name>North Pad</name><ExtendedData><Data name=\"target_formation\"><value>Wolfcamp A</value></Data><Data name=\"wps\"><value>4</value></Data></ExtendedData><Polygon><outerBoundaryIs><LinearRing><coordinates>-101.95,31.93 -101.938,31.93 -101.938,31.957 -101.95,31.957 -101.95,31.93</coordinates></LinearRing></outerBoundaryIs></Polygon></Placemark></Document></kml>",
                    "formation": "WOLFCAMP B"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The pads in file order, and their wells.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PadsReadResponse"
                },
                "example": {
                  "count": 2,
                  "wells_count": 6,
                  "crs": {
                    "code": "EPSG:4326",
                    "name": "WGS 84",
                    "source": "file",
                    "datum_shift": null,
                    "max_offset_ft": 0,
                    "alternatives": []
                  },
                  "name_field": "pad_name",
                  "fields": [
                    "pad_name",
                    "target_formation",
                    "wps",
                    "til_date",
                    "spacing"
                  ],
                  "columns": {
                    "formation": "target_formation",
                    "til_date": "til_date",
                    "lateral_length_ft": null,
                    "tvd_ft": null,
                    "fluid_bbl_per_ft": null,
                    "proppant_lb_per_ft": null,
                    "wells_per_section": "wps",
                    "spacing_ft": "spacing",
                    "azimuth_deg": null,
                    "setback_ft": null,
                    "landing_fraction": null
                  },
                  "unknown_formations": [
                    {
                      "value": "Barnett",
                      "pads": 1
                    }
                  ],
                  "skipped": [],
                  "warnings": [
                    "Left out 1 of 3 pads; pads[].issues says why.",
                    "1 pad names a formation this dataset lacks, listed in unknown_formations; GET /formations lists the ones it has."
                  ],
                  "pads": [
                    {
                      "id": 0,
                      "name": "North Pad",
                      "outline": [
                        [
                          -101.95,
                          31.93
                        ],
                        [
                          -101.938,
                          31.93
                        ],
                        [
                          -101.938,
                          31.957
                        ],
                        [
                          -101.95,
                          31.957
                        ]
                      ],
                      "acres": 840.01,
                      "azimuth_deg": 0,
                      "wells_per_section": 4,
                      "formation": "WOLFCAMP A",
                      "lateral_length_ft": null,
                      "setback_ft": 0,
                      "til_date": "2027-03-01",
                      "fluid_bbl_per_ft": null,
                      "proppant_lb_per_ft": null,
                      "tvd_ft": null,
                      "landing_fraction": null,
                      "wells": [
                        0,
                        1,
                        2
                      ],
                      "issues": [],
                      "left_out": false
                    },
                    {
                      "id": 1,
                      "name": "Middle Pad",
                      "outline": [
                        [
                          -101.93,
                          31.93
                        ],
                        [
                          -101.918,
                          31.93
                        ],
                        [
                          -101.918,
                          31.957
                        ],
                        [
                          -101.93,
                          31.957
                        ]
                      ],
                      "acres": 840.01,
                      "azimuth_deg": 0,
                      "wells_per_section": 4,
                      "formation": "WOLFCAMP B",
                      "lateral_length_ft": null,
                      "setback_ft": 0,
                      "til_date": null,
                      "fluid_bbl_per_ft": null,
                      "proppant_lb_per_ft": null,
                      "tvd_ft": null,
                      "landing_fraction": null,
                      "wells": [
                        3,
                        4,
                        5
                      ],
                      "issues": [],
                      "left_out": false
                    },
                    {
                      "id": 2,
                      "name": "South Pad",
                      "outline": [
                        [
                          -101.95,
                          31.9
                        ],
                        [
                          -101.938,
                          31.9
                        ],
                        [
                          -101.938,
                          31.92
                        ],
                        [
                          -101.95,
                          31.92
                        ]
                      ],
                      "acres": 622.46,
                      "azimuth_deg": 0,
                      "wells_per_section": 6,
                      "formation": null,
                      "lateral_length_ft": null,
                      "setback_ft": 0,
                      "til_date": null,
                      "fluid_bbl_per_ft": null,
                      "proppant_lb_per_ft": null,
                      "tvd_ft": null,
                      "landing_fraction": null,
                      "wells": [],
                      "issues": [
                        "formation \"Barnett\" isn't one of this dataset's (GET /formations lists them)"
                      ],
                      "left_out": true
                    }
                  ],
                  "wells": [
                    {
                      "shl": [
                        -101.9482546,
                        31.93
                      ],
                      "bhl": [
                        -101.9482546,
                        31.957
                      ],
                      "formation": "WOLFCAMP A",
                      "pad": "North Pad"
                    },
                    {
                      "shl": [
                        -101.944,
                        31.93
                      ],
                      "bhl": [
                        -101.944,
                        31.957
                      ],
                      "formation": "WOLFCAMP A",
                      "pad": "North Pad"
                    },
                    {
                      "shl": [
                        -101.9397454,
                        31.93
                      ],
                      "bhl": [
                        -101.9397454,
                        31.957
                      ],
                      "formation": "WOLFCAMP A",
                      "pad": "North Pad"
                    },
                    {
                      "shl": [
                        -101.9282546,
                        31.93
                      ],
                      "bhl": [
                        -101.9282546,
                        31.957
                      ],
                      "formation": "WOLFCAMP B",
                      "pad": "Middle Pad"
                    },
                    {
                      "shl": [
                        -101.924,
                        31.93
                      ],
                      "bhl": [
                        -101.924,
                        31.957
                      ],
                      "formation": "WOLFCAMP B",
                      "pad": "Middle Pad"
                    },
                    {
                      "shl": [
                        -101.9197454,
                        31.93
                      ],
                      "bhl": [
                        -101.9197454,
                        31.957
                      ],
                      "formation": "WOLFCAMP B",
                      "pad": "Middle Pad"
                    }
                  ],
                  "pad_values": [
                    {
                      "pad": "North Pad",
                      "til_date": "2027-03-01"
                    },
                    {
                      "pad": "Middle Pad"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/completion-designs/read": {
      "post": {
        "operationId": "readCompletionDesigns",
        "tags": [
          "Design"
        ],
        "summary": "Read completion designs from a file",
        "description": "Completion designs from a CSV or an Excel workbook as named designs, ready for a plan's `designs`, with what became of each row. Nothing is stored: send the file again to read it again.\n\n**Upload.** Send the file as `multipart/form-data`, as `curl -F file=@designs.xlsx -F sheet=Designs <origin>/api/v1/completion-designs/read`, or its text as `csv` in a JSON body. A zip is read as a workbook (one without `[Content_Types].xml` is a 400), an .xls or a workbook saved with a password is a 400, and anything else is a CSV. `sheet` picks a workbook's sheet by name (exact, else in any case) or index from 0, else the first, with a warning when there are more; one the workbook lacks is a 400 with `details.sheets`. A name of digits only reads as an index, so pick a sheet by its position in `sheets` (`include` `[\"sheets\"]`), where a name over 31 characters is cut to 31 and ends in ….\n\n**Columns.** Each role reads the first of its names the file has, compared lowercased with all but letters and digits dropped (Fluid (bbl/ft) is fluidbblft):\n\n- `name`: designname, design, completiondesign, name\n- `formation`: noviformation, targetformation, formation, targetzone, landingzone, zone\n- `fluid_bbl_per_ft`: novicalcfluidperlength, fluidbblperft, fluidperft, fluidperlength, fluid, fluidbblft\n- `fluid_gal_per_ft`: fluidgalperft, galperft, fluidgalft\n- `proppant_lb_per_ft`: novicalcproppantperlength, proppantlbperft, proppantperft, proppantperlength, propperft, proppant, sand, sandlbperft, proppantlbft, sandlbft\n- `fluid_bbl_per_stage`: fluidbblperstage, fluidperstage, fluidbblstage\n- `proppant_lb_per_stage`: proppantlbperstage, proppantperstage, sandperstage, proppantlbstage, sandlbstage\n- `stage_length_ft`: novistagelength, novicalcstagespacing, stagelengthft, stagelength, stagespacing, stagespacingft, stagelen\n- `clusters_per_stage`: noviclustersperstage, novicalcclustersperstage, clustersperstage, cluststg\n- `frac_rate_bbl_per_min`: novifracrate, fracratebblpermin, fracrate, fracratebblmin, fracratebpm, fracbpm\n\nOther columns (costs) are listed in `fields` and not read; `clusters_per_stage` and `frac_rate_bbl_per_min` are in `columns` only when the file has them. A file with no fluid or proppant column is a 400 with `details.fields`.\n\n**Rows.** A CSV row with more cells than the header is left out.\n\n- Rows with the same name are one design; a blank name, or one over 60 characters, leaves the row out.\n- A row without a formation sets its design's values; one with a formation (any case) adds an entry to the design's `formations`, at most 100 (later ones are left out). An unknown formation leaves the row out and is counted in `unknown_formations`.\n- A repeat of a name and formation, or of a name's own row, is left out, naming the row it repeats.\n\n**Values.** Numbers are written as 2700 or 2.7e3, without thousands separators.\n\n- Fluid is bbl/ft, or gal/ft divided by 42. Per-stage fluid and proppant are divided by the row's stage length (dropped with an issue without one over 0). A row with two forms reads bbl/ft over gal/ft and per ft over per stage, and the other gets an issue.\n- Fluid is over 0 and under 1,000 bbl/ft and proppant over 0 and under 20,000 lb/ft; another value is dropped with an issue, and a row left with neither is left out.\n- Stage length (ft), clusters per stage and frac rate (bbl/min) are kept on the design or formation entry, each dropped with an issue out of range: stage length over 0 and under 2,000 ft, clusters per stage over 0 and under 100, frac rate over 0 and under 500 bbl/min.\n- A stage length that converted per-stage values is kept only on a model set whose models read it. A warning names filled stage columns the set's models don't read.\n\n**Limits.** The 10 MB request body (a 413); 1,000 rows and 100 designs, each a 400 with `details.max` and `details.count`. POST /plans takes 10 `designs`, so a warning comes past 10, and POST /forecasts 25.\n\n**Errors.** 400 with `details.field` naming `file`, `csv`, `sheet`, or `include` and `include[0]` (an unknown value, with `details.allowed`).",
        "requestBody": {
          "required": true,
          "description": "The file as a multipart upload, or CSV text in JSON.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/CompletionDesignsUpload"
              },
              "encoding": {
                "file": {
                  "contentType": "text/csv, text/tab-separated-values, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
                }
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompletionDesignsReadRequest"
              },
              "example": {
                "csv": "Design Name,Formation,Fluid (bbl/ft),Proppant (lb/ft)\nGen 3 slickwater,,55,2700\nGen 3 slickwater,WOLFCAMP B,60,2900\nGen 2 hybrid,,40,2000\nLean,,30,1500"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Named designs and every row in file order.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompletionDesignsRead"
                },
                "example": {
                  "count": 3,
                  "format": "csv",
                  "columns": {
                    "name": "Design Name",
                    "formation": "Formation",
                    "fluid_bbl_per_ft": "Fluid (bbl/ft)",
                    "fluid_gal_per_ft": null,
                    "proppant_lb_per_ft": "Proppant (lb/ft)",
                    "fluid_bbl_per_stage": null,
                    "proppant_lb_per_stage": null,
                    "stage_length_ft": null
                  },
                  "fields": [
                    "Design Name",
                    "Formation",
                    "Fluid (bbl/ft)",
                    "Proppant (lb/ft)"
                  ],
                  "designs": [
                    {
                      "name": "Gen 3 slickwater",
                      "fluid_bbl_per_ft": 55,
                      "proppant_lb_per_ft": 2700,
                      "formations": [
                        {
                          "formation": "WOLFCAMP B",
                          "fluid_bbl_per_ft": 60,
                          "proppant_lb_per_ft": 2900
                        }
                      ]
                    },
                    {
                      "name": "Gen 2 hybrid",
                      "fluid_bbl_per_ft": 40,
                      "proppant_lb_per_ft": 2000,
                      "formations": []
                    },
                    {
                      "name": "Lean",
                      "fluid_bbl_per_ft": 30,
                      "proppant_lb_per_ft": 1500,
                      "formations": []
                    }
                  ],
                  "rows": [
                    {
                      "id": 0,
                      "name": "Gen 3 slickwater",
                      "formation": null,
                      "design": 0,
                      "issues": []
                    },
                    {
                      "id": 1,
                      "name": "Gen 3 slickwater",
                      "formation": "WOLFCAMP B",
                      "design": 0,
                      "issues": []
                    },
                    {
                      "id": 2,
                      "name": "Gen 2 hybrid",
                      "formation": null,
                      "design": 1,
                      "issues": []
                    },
                    {
                      "id": 3,
                      "name": "Lean",
                      "formation": null,
                      "design": 2,
                      "issues": []
                    }
                  ],
                  "unknown_formations": [],
                  "warnings": []
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/forecast-sources/read": {
      "post": {
        "operationId": "readForecastSource",
        "tags": [
          "Forecast sources"
        ],
        "summary": "Read a forecast file",
        "description": "Reads a booked forecast file into decline curves, one per well, reserves category, design and stream. `rows` lists the rows with an issue and `warnings` what to check. Nothing is stored: POST /forecast-sources saves a read.\n\n**Formats.** The header picks the format, and `options.format` overrides it. Numbers are decimals only: 0x1F is a row issue, not 31.\n\n- `valnav_decline`: a Val Nav decline CSV, its six segment templates, Di and Df in percent.\n- `valnav_constants`: a Val Nav constants CSV of ratios, sent as `constants` with a decline file.\n- `novi_arps`: Novi's own arps.csv, from POST /exports.\n- `combocurve_parameters`: a ComboCurve forecast parameters CSV. Series `best` reads as P50, and wells key on Chosen ID, else INPT ID. Incline and ratio segments are row issues.\n- `mosaic_decline`: a Mosaic decline CSV saved from its workbook. Di, else Dei, else Desi; ∆ T over Tf; dates as text or spreadsheet serials; ratios decline on the parent's cumulative volume.\n- `aries`: ARIES import text as Novi's ARIES export writes it, from the production section's OIL, GAS, WTR and CND lines. Ratio, LIN and dated segments are row issues.\n  - It is told by its first two non-blank lines: a well's name in column 1, then PRODUCTION.\n  - Its lines state their units and have no columns, so `options.units` and `options.columns` are 400s with it.\n  - A row's `id` is a line's index from 0, blank lines counted. A well name over 200 characters is a row issue that leaves its curves out.\n\n**Upload.** Send the file as a `multipart/form-data` `file` part, with an optional `constants` part for a Val Nav decline file. Clients limited to JSON send the text as `csv` and `constants_csv`.\n\n**Workbooks.** Either part may be an Excel workbook (.xlsx), read as a CSV of the sheet's stored cell values would be. `options.sheet` picks the sheet; absent, the first, with a warning when there are more. A constants workbook reads its first sheet.\n\n- Dates are serial numbers in the workbook's own date system: 1900, or 1904 when it says so.\n- Formulas read as the values the workbook saved (none is calculated), numbers as stored, unrounded whatever their display format, and booleans as TRUE or FALSE.\n- A row with a formula error (#N/A, #DIV/0!) in a column the format reads is left out, with the error in `rows[].issues`.\n\n**Options.** `options` says how to read the file; see its fields. Condensate reads as oil unless `products` maps it. In Novi arps.csv, P50 reads as category P50 unless `p_levels` maps it, and P10 or P90 without a map is left out with a warning.\n\n**Include.** `warning_codes` adds each warning's stable `code` and the fields it names (a product, a count, a unit system), so a client can word it against its own controls. `sheets` adds a workbook `file`'s `sheet` and `sheets`, for a sheet list; a constants workbook isn't listed, and CSV text answers as without it.\n\n**Limits.**\n\n- The 64 MB request body; a body over it is a 413.\n- 30,000 curves (past them, a 400 with `details.max` and `details.count`) and 600,000 lines of ARIES text (a 400 with `details.max`).\n- A workbook: 1,000 zip entries, 32 MB for each part it reads and 64 MB in all, 1,000,000 shared strings, 2,000,000 cells with a value and 500 columns.\n- A workbook's reading work, set to hold the server under a second (about 50,000 rows of 13 columns): past it, a 400 with `details.max_work`. Save a larger sheet as CSV.\n\n**Errors.** A 400 naming the fix refuses an .xls or a workbook saved with a password; .xlsm, .xltx and .xlsb; a part declaring a DTD or entities; a damaged workbook; an unknown `options.sheet` (`details.sheets` lists the sheets); and `options.sheet` with CSV text.",
        "requestBody": {
          "required": true,
          "description": "The file: uploaded as multipart/form-data, or in a JSON body for clients limited to JSON.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/ForecastSourceUpload"
              },
              "encoding": {
                "file": {
                  "contentType": "text/csv, text/plain, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
                },
                "constants": {
                  "contentType": "text/csv, text/plain, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
                }
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ForecastSourceReadRequest"
              },
              "example": {
                "csv": "UWI,Rescat,Product,Segment Index,Start Date,Qi,Qf,Di (Nominal),Df (Nominal),N\nExample 1H,PUD,OIL,1,2027-03-01,620,,85,8,1.1\nExample 1H,PUD,OIL,2,,,5,,,0\nExample 1H,PUD,GAS,1,2027-03-01,2400,50,70,,1\nExample 2H,PUD,OIL,1,2027-06-01,0x1F,5,85,,1",
                "options": {
                  "units": "imperial"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The curves, and the rows with an issue.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceRead"
                },
                "example": {
                  "format": "valnav_decline",
                  "detected_from": [
                    "UWI",
                    "Rescat",
                    "Product",
                    "Segment Index",
                    "Start Date",
                    "Qi",
                    "Di (Nominal)",
                    "Df (Nominal)",
                    "N"
                  ],
                  "units": {
                    "system": "imperial",
                    "from": "options",
                    "rates": {
                      "oil": "bbl/d",
                      "gas": "mcf/d",
                      "water": "bbl/d"
                    },
                    "ratios": {},
                    "row": null
                  },
                  "products": {
                    "found": [
                      {
                        "value": "OIL",
                        "curves": 2
                      },
                      {
                        "value": "GAS",
                        "curves": 1
                      }
                    ],
                    "mapped": [
                      {
                        "value": "OIL",
                        "stream": "oil",
                        "from": null
                      },
                      {
                        "value": "GAS",
                        "stream": "gas",
                        "from": null
                      }
                    ],
                    "skipped": []
                  },
                  "gas_basis": "raw",
                  "reserves_categories": [
                    {
                      "value": "PUD",
                      "curves": 3,
                      "kept": true
                    }
                  ],
                  "curves": [
                    {
                      "well_id": "Example 1H",
                      "reserves_category": "PUD",
                      "design": null,
                      "stream": "oil",
                      "product": "OIL",
                      "ratio": null,
                      "profile": "valnav",
                      "start_date": "2027-03-01T00:00:00.000Z",
                      "template": "two_segment_hyperbolic",
                      "segments": [
                        {
                          "start": 0,
                          "qi": 620,
                          "di": 0.85,
                          "b": 1.1,
                          "df": 0.08,
                          "end": 3759.849264705882,
                          "qf": 72.33781417182348
                        },
                        {
                          "start": 3759.849264705882,
                          "qi": 72.33781417182348,
                          "di": 0.08,
                          "b": 0,
                          "qf": 4.999999999999999,
                          "end": 15958.533746937479,
                          "df": 0.08
                        }
                      ]
                    },
                    {
                      "well_id": "Example 1H",
                      "reserves_category": "PUD",
                      "design": null,
                      "stream": "gas",
                      "product": "GAS",
                      "ratio": null,
                      "profile": "valnav",
                      "start_date": "2027-03-01T00:00:00.000Z",
                      "template": "single_segment",
                      "segments": [
                        {
                          "start": 0,
                          "qi": 2400,
                          "di": 0.7,
                          "b": 1,
                          "qf": 49.99999999999999,
                          "end": 24523.425000000003,
                          "df": 0.01458333333333333
                        }
                      ]
                    }
                  ],
                  "rows": [
                    {
                      "file": "csv",
                      "id": 3,
                      "well_id": "Example 2H",
                      "product": "OIL",
                      "segment": 1,
                      "left_out": true,
                      "issues": [
                        "Qi \"0x1F\" isn't a number"
                      ]
                    }
                  ],
                  "warnings": [
                    "Left out 1 of 3 curves; rows[].issues says why."
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "description": "The request body is over 64 MB.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        },
        "parameters": []
      }
    },
    "/forecast-sources": {
      "get": {
        "operationId": "listForecastSources",
        "tags": [
          "Forecast sources"
        ],
        "summary": "List forecast sources",
        "description": "The forecast sources the caller can read, newest first: each one's listing record, without its curves, read report or pairs (GET one for those). A private source lists only for its creator. Invalid limit or cursor is 400. A server without a state store answers 409 \"Forecast sources need a state store; this server keeps plans in memory\".",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Page size, 1-100.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Forecast sources and next cursor.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForecastSourceList"
                },
                "example": {
                  "items": [
                    {
                      "id": "00000000-0000-4000-8000-000000000003",
                      "name": "Booked PUD",
                      "format": "valnav_decline",
                      "units": "imperial",
                      "conventions": "valnav",
                      "gas_basis": "raw",
                      "curve_count": 2,
                      "well_count": 1,
                      "file": {
                        "name": "decline.csv",
                        "bytes": 243,
                        "sha256": "b96fecf06aef5102431a47b05b9588c280a084bbc7c258b8e97edf64544afbc4"
                      },
                      "visibility": "tenant",
                      "created_by": null,
                      "created_at": "2026-01-01T00:00:00Z",
                      "updated_at": "2026-01-01T00:00:00Z",
                      "plan_id": null,
                      "plan_linked": false,
                      "etag": "\"opaque-etag\""
                    }
                  ],
                  "next_cursor": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "A server without a state store answers 409 \"Forecast sources need a state store; this server keeps plans in memory\".",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        }
      },
      "post": {
        "operationId": "createForecastSource",
        "tags": [
          "Forecast sources"
        ],
        "summary": "Save a forecast source",
        "description": "Reads a file as POST /forecast-sources/read does and keeps the read as a forecast source: its curves, the read report's rows, and the file's name, bytes and SHA-256, but not the file. Send the read's body plus `name`; the answer is the read with the saved `source`.\n\n**Visibility.** Anyone but its creator gets 404 for a `private` source. Without a signed-in user (a server's configured user), `private` is a 400: send `tenant`.\n\n**A linked plan.** `plan_id` names a done plan the caller can read: else a 404, or a 409 while it runs or after it failed. Deleting the plan keeps the source, which then reads its `plan_id` and `pairs` with `plan_linked: false`.\n\n**Retries.** An `Idempotency-Key` makes a retry safe, per tenant and creator: the same key with the same file (by its SHA-256 and the text parts, or the same JSON body) returns the first source with `Idempotent-Replayed: true`. With another file it is a 409.\n\n**Errors.** A file that reads no curves is a 400. A server without a state store answers 409 \"Forecast sources need a state store; this server keeps plans in memory\".",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "The file and its name: uploaded as multipart/form-data, or in a JSON body.",
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/ForecastSourceSaveUpload"
              },
              "encoding": {
                "file": {
                  "contentType": "text/csv, text/plain, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
                },
                "constants": {
                  "contentType": "text/csv, text/plain, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
                }
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ForecastSourceSaveRequest"
              },
              "example": {
                "csv": "UWI,Rescat,Product,Segment Index,Start Date,Qi,Qf,Di (Nominal),Df (Nominal),N\nExample 1H,PUD,OIL,1,2027-03-01,620,,85,8,1.1\nExample 1H,PUD,OIL,2,,,5,,,0\nExample 1H,PUD,GAS,1,2027-03-01,2400,50,70,,1\nExample 2H,PUD,OIL,1,2027-06-01,0x1F,5,85,,1",
                "options": {
                  "units": "imperial"
                },
                "name": "Booked PUD",
                "visibility": "tenant",
                "file_name": "decline.csv"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The read and the saved source, with its ETag.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/VersionETag"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForecastSourceSaved"
                },
                "example": {
                  "format": "valnav_decline",
                  "detected_from": [
                    "UWI",
                    "Rescat",
                    "Product",
                    "Segment Index",
                    "Start Date",
                    "Qi",
                    "Di (Nominal)",
                    "Df (Nominal)",
                    "N"
                  ],
                  "units": {
                    "system": "imperial",
                    "from": "options",
                    "rates": {
                      "oil": "bbl/d",
                      "gas": "mcf/d",
                      "water": "bbl/d"
                    },
                    "ratios": {},
                    "row": null
                  },
                  "products": {
                    "found": [
                      {
                        "value": "OIL",
                        "curves": 2
                      },
                      {
                        "value": "GAS",
                        "curves": 1
                      }
                    ],
                    "mapped": [
                      {
                        "value": "OIL",
                        "stream": "oil",
                        "from": null
                      },
                      {
                        "value": "GAS",
                        "stream": "gas",
                        "from": null
                      }
                    ],
                    "skipped": []
                  },
                  "gas_basis": "raw",
                  "reserves_categories": [
                    {
                      "value": "PUD",
                      "curves": 3,
                      "kept": true
                    }
                  ],
                  "curves": [
                    {
                      "well_id": "Example 1H",
                      "reserves_category": "PUD",
                      "design": null,
                      "stream": "oil",
                      "product": "OIL",
                      "ratio": null,
                      "profile": "valnav",
                      "start_date": "2027-03-01T00:00:00.000Z",
                      "template": "two_segment_hyperbolic",
                      "segments": [
                        {
                          "start": 0,
                          "qi": 620,
                          "di": 0.85,
                          "b": 1.1,
                          "df": 0.08,
                          "end": 3759.849264705882,
                          "qf": 72.33781417182348
                        },
                        {
                          "start": 3759.849264705882,
                          "qi": 72.33781417182348,
                          "di": 0.08,
                          "b": 0,
                          "qf": 4.999999999999999,
                          "end": 15958.533746937479,
                          "df": 0.08
                        }
                      ]
                    },
                    {
                      "well_id": "Example 1H",
                      "reserves_category": "PUD",
                      "design": null,
                      "stream": "gas",
                      "product": "GAS",
                      "ratio": null,
                      "profile": "valnav",
                      "start_date": "2027-03-01T00:00:00.000Z",
                      "template": "single_segment",
                      "segments": [
                        {
                          "start": 0,
                          "qi": 2400,
                          "di": 0.7,
                          "b": 1,
                          "qf": 49.99999999999999,
                          "end": 24523.425000000003,
                          "df": 0.01458333333333333
                        }
                      ]
                    }
                  ],
                  "rows": [
                    {
                      "file": "csv",
                      "id": 3,
                      "well_id": "Example 2H",
                      "product": "OIL",
                      "segment": 1,
                      "left_out": true,
                      "issues": [
                        "Qi \"0x1F\" isn't a number"
                      ]
                    }
                  ],
                  "warnings": [
                    "Left out 1 of 3 curves; rows[].issues says why."
                  ],
                  "source": {
                    "id": "00000000-0000-4000-8000-000000000003",
                    "name": "Booked PUD",
                    "format": "valnav_decline",
                    "units": "imperial",
                    "conventions": "valnav",
                    "gas_basis": "raw",
                    "curve_count": 2,
                    "well_count": 1,
                    "file": {
                      "name": "decline.csv",
                      "bytes": 243,
                      "sha256": "b96fecf06aef5102431a47b05b9588c280a084bbc7c258b8e97edf64544afbc4"
                    },
                    "visibility": "tenant",
                    "created_by": null,
                    "created_at": "2026-01-01T00:00:00Z",
                    "updated_at": "2026-01-01T00:00:00Z",
                    "plan_id": null,
                    "plan_linked": false,
                    "etag": "\"opaque-etag\"",
                    "reserves_categories": [
                      {
                        "value": "PUD",
                        "curves": 2
                      }
                    ],
                    "pairs": null,
                    "read_report": {
                      "rows": [
                        {
                          "file": "csv",
                          "id": 3,
                          "issues": [
                            "Qi \"0x1F\" isn't a number"
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The linked plan is still running or failed, or the Idempotency-Key was already used with another file; or, with Redis, the first request with this Idempotency-Key is still being made (after a 30 s wait); retry shortly with the same key. A server without a state store answers 409 \"Forecast sources need a state store; this server keeps plans in memory\".",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "The request body is over 64 MB.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "description": "With Redis, the Redis that keeps Idempotency-Key records isn't answering; retry with the same key.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/forecast-sources/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Forecast source id from POST /forecast-sources or GET /forecast-sources.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "getForecastSource",
        "tags": [
          "Forecast sources"
        ],
        "summary": "Get a forecast source",
        "description": "A forecast source with its read report, reserves categories, pairs and ETag; `include=volumes` adds its curves with their volumes and EUR.\n\n**Volumes.** Each curve's cumulative volume at `ip_days` and its EUR, from Novi's Arps decline calculation under its file format's conventions (GET /conventions include=decline_profiles): bbl for oil and water, mcf for gas, to 0.1, from day 0, the earliest start date of the curve's well, reserves category and design. A curve the calculation can't run has `values: null` and `error`.\n\n**Linked plan.** A link to a plan that is gone, or that the caller can't read, keeps `plan_id` and `pairs`, with `plan_linked: false`.\n\n**Errors.** An unknown, deleted, other-tenant or someone else's private source is 404; `ip_days` without include=volumes, or one GET /dataset doesn't list, is 400. A server without a state store answers 409 \"Forecast sources need a state store; this server keeps plans in memory\".",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "description": "volumes adds the curves with their volumes; other or duplicate names are 400.",
            "schema": {
              "type": "string",
              "enum": [
                "volumes"
              ]
            }
          },
          {
            "name": "ip_days",
            "in": "query",
            "description": "With include=volumes: comma-separated ip_days from GET /dataset `ip_days`, as POST /forecasts takes them, such as 30,90,360. Absent, every one.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The forecast source.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/VersionETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForecastSource"
                },
                "example": {
                  "id": "00000000-0000-4000-8000-000000000003",
                  "name": "Booked PUD",
                  "format": "valnav_decline",
                  "units": "imperial",
                  "conventions": "valnav",
                  "gas_basis": "raw",
                  "curve_count": 2,
                  "well_count": 1,
                  "file": {
                    "name": "decline.csv",
                    "bytes": 243,
                    "sha256": "b96fecf06aef5102431a47b05b9588c280a084bbc7c258b8e97edf64544afbc4"
                  },
                  "visibility": "tenant",
                  "created_by": null,
                  "created_at": "2026-01-01T00:00:00Z",
                  "updated_at": "2026-01-01T00:00:00Z",
                  "plan_id": null,
                  "plan_linked": false,
                  "etag": "\"opaque-etag\"",
                  "reserves_categories": [
                    {
                      "value": "PUD",
                      "curves": 2
                    }
                  ],
                  "pairs": null,
                  "read_report": {
                    "rows": [
                      {
                        "file": "csv",
                        "id": 3,
                        "issues": [
                          "Qi \"0x1F\" isn't a number"
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A server without a state store answers 409 \"Forecast sources need a state store; this server keeps plans in memory\".",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        }
      },
      "patch": {
        "operationId": "updateForecastSource",
        "tags": [
          "Forecast sources"
        ],
        "summary": "Rename, share, link or pair a source",
        "description": "Change a forecast source's `name`, `visibility`, `plan_id` or `pairs` (at least one). A refused request changes nothing, the plan to link included; only the creator, signed in, can make a source private.\n\n**Links and pairs.** `plan_id` links and saves a done plan the caller can read, as on create; null unlinks. Moving the link to another plan clears `pairs` unless the body sends new ones.\n\n- `pairs` matches source Well IDs to the plan's well indexes (GET /plans/{id}/wells/{index}): one plan well per source well, at most the source's well count. Null clears them.\n- While the linked plan is gone (`plan_linked: false`), new `pairs` need `plan_id` too.\n\n**Conflicts.** `If-Match` with the ETag changes only the version you read; a stale one is a 409 with `details.etag`. Without it, a change made between the server's read and its write is a 409 too.\n\n**Errors.** Unknown fields are a 400 listing the allowed ones. A server without a state store answers 409 \"Forecast sources need a state store; this server keeps plans in memory\".",
        "parameters": [
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The source's ETag, including quotes.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "The fields to change.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ForecastSourcePatch"
              },
              "example": {
                "name": "Booked PUD 2027",
                "visibility": "tenant"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated source and its ETag.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/VersionETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForecastSource"
                },
                "example": {
                  "id": "00000000-0000-4000-8000-000000000003",
                  "name": "Booked PUD",
                  "format": "valnav_decline",
                  "units": "imperial",
                  "conventions": "valnav",
                  "gas_basis": "raw",
                  "curve_count": 2,
                  "well_count": 1,
                  "file": {
                    "name": "decline.csv",
                    "bytes": 243,
                    "sha256": "b96fecf06aef5102431a47b05b9588c280a084bbc7c258b8e97edf64544afbc4"
                  },
                  "visibility": "tenant",
                  "created_by": null,
                  "created_at": "2026-01-01T00:00:00Z",
                  "updated_at": "2026-01-01T00:00:00Z",
                  "plan_id": null,
                  "plan_linked": false,
                  "etag": "\"opaque-etag\"",
                  "reserves_categories": [
                    {
                      "value": "PUD",
                      "curves": 2
                    }
                  ],
                  "pairs": null,
                  "read_report": {
                    "rows": [
                      {
                        "file": "csv",
                        "id": 3,
                        "issues": [
                          "Qi \"0x1F\" isn't a number"
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A stale If-Match, or without one a change made while the request ran (`details.etag` is the current one); or the plan to link is running or failed. A server without a state store answers 409 \"Forecast sources need a state store; this server keeps plans in memory\".",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        }
      },
      "delete": {
        "operationId": "deleteForecastSource",
        "tags": [
          "Forecast sources"
        ],
        "summary": "Delete a forecast source",
        "description": "Delete a forecast source and its curves; its linked plan is untouched. Anyone who can read it can delete it. An unknown or unreadable source is 404. A server without a state store answers 409 \"Forecast sources need a state store; this server keeps plans in memory\".",
        "responses": {
          "204": {
            "description": "Deleted.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A server without a state store answers 409 \"Forecast sources need a state store; this server keeps plans in memory\".",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        },
        "parameters": []
      }
    },
    "/forecasts": {
      "post": {
        "operationId": "createForecast",
        "tags": [
          "Forecasts"
        ],
        "summary": "Forecast drawn wells",
        "description": "Runs up to 50 drawn wells through TVD estimates, spacing, spacing features, subsurface interpolation and the oil, gas and water models, together, so they count as each other's spacing neighbors.\n\n**Designs.** Each well is forecast with every design in `designs` (up to 25); spacing and its features run once, with the first. A well's own `fluid_bbl_per_ft` and `proppant_lb_per_ft` need one design.\n\n**What you get.** Each well's inputs, the TVD used, one forecast per design, its spacing neighbors, its spacing features at ip_day 1 and its subsurface values, and `timings` in ms.\n\n**Options.** Each is described on its field.\n\n- `pdp: false` leaves existing wells out of spacing; `scenarios`, `pads` and `formations` set values per scenario, pad and formation; `layout` lays the wells out from a fill boundary.\n- `til_date` schedules wells: the later of two neighbors is the child of the earlier when they are 90 days or more apart.\n- For sweeps of many layouts and designs, `ip_days` keeps only the ip_days you need and `summary: true` returns plan summaries (PlanWellSummary).\n- `eur`, `eur_curve`, `bands` (`bands: {error}` for a stream without a bands fit), `band_eur`, `totals` (per design, as GET /plans/{id} gives them) and `boe` add EUR, P10/P90 bands, totals and BOE.\n- `explain: true` (up to 10 wells × designs) adds `explanations`, one per design: SHAP per ip_day and the contributing training wells. The `explain_` fields shape them as on GET /plans/{id}/wells/{index}/explanations/{design}.\n\n**Scenarios.** With a `scenario` on every well, up to 10 alternatives run side by side: each scenario's wells space against only each other and existing wells, in one spacing run per scenario (so spacing time grows with them), then the features and models run once over all. Each well's `inputs.scenario` names its own; a scenario's forecast equals a request of its wells alone, up to how other drawn wells are labeled. A spacing worker without scenario support answers 502 (`details.worker` spacing).\n\n**Drawn parents.** A drawn parent reads as 0 in its drawn children's neighbor-production features; POST /plans chains depletion (`depletion_chain`).\n\n**Async.** With `async: true` the forecast runs as a job (see `async`): 202 with a ForecastJob and its `Location`, then GET /forecasts/{id}?wait=25.\n\n- An `Idempotency-Key` replays the first job, as on POST /plans; without `async` it is ignored.\n- A job belongs to the request tenant (your company), and only that tenant reads it, from any model set.\n- At most 50 async forecasts run at once per tenant, across model sets and server tasks; the next is a 409 with `Retry-After: 1`.\n- A job still running 30 minutes after it started fails (`unavailable`).\n- A 404 is an `Idempotency-Key` replay of an expired job, or a tenant not allowed.\n\n**Job storage.** Where jobs live decides how long they last.\n\n- With Redis, every server task shares the jobs, each kept for an hour after it finishes; while Redis isn't answering, async calls are a 503.\n- A job whose task stops runs again on another task, about 5 s after a shutdown and 20 s after a crash, keeping its deadline. After 2 crash takeovers, a further crash fails it (`unavailable`); one no task takes over reads as failed a minute after its deadline.\n- Without Redis, a server keeps its newest 200 jobs in memory, each for an hour, lost on a restart.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Drawn wells, 1 to 50, or a layout of up to 50.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ForecastRequest"
              },
              "examples": {
                "explained": {
                  "summary": "Explained",
                  "value": {
                    "wells": [
                      {
                        "shl": [
                          -101.93,
                          31.93
                        ],
                        "bhl": [
                          -101.93,
                          31.957
                        ],
                        "formation": "WOLFCAMP A",
                        "tvd_ft": null
                      }
                    ],
                    "designs": [
                      {
                        "name": "Recent median",
                        "fluid_bbl_per_ft": null,
                        "proppant_lb_per_ft": null
                      },
                      {
                        "name": "Upsized",
                        "fluid_bbl_per_ft": 60,
                        "proppant_lb_per_ft": 3000
                      }
                    ],
                    "pdp": true,
                    "explain": true
                  }
                },
                "scenarios": {
                  "summary": "One stick in three benches, a scenario each",
                  "value": {
                    "wells": [
                      {
                        "shl": [
                          -101.93,
                          31.93
                        ],
                        "bhl": [
                          -101.93,
                          31.957
                        ],
                        "formation": "WOLFCAMP A",
                        "scenario": "WOLFCAMP A"
                      },
                      {
                        "shl": [
                          -101.93,
                          31.93
                        ],
                        "bhl": [
                          -101.93,
                          31.957
                        ],
                        "formation": "WOLFCAMP B",
                        "scenario": "WOLFCAMP B"
                      },
                      {
                        "shl": [
                          -101.93,
                          31.93
                        ],
                        "bhl": [
                          -101.93,
                          31.957
                        ],
                        "formation": "LOWER SPRABERRY SHALE",
                        "scenario": "LOWER SPRABERRY SHALE"
                      }
                    ],
                    "designs": [
                      {
                        "name": "Recent median"
                      }
                    ],
                    "eur": true,
                    "summary": true,
                    "ip_days": [
                      360,
                      720,
                      1080
                    ]
                  }
                },
                "boe": {
                  "summary": "totals and boe with EUR and bands",
                  "value": {
                    "wells": [
                      {
                        "shl": [
                          -101.93,
                          31.93
                        ],
                        "bhl": [
                          -101.93,
                          31.957
                        ],
                        "formation": "WOLFCAMP A"
                      },
                      {
                        "shl": [
                          -101.927,
                          31.93
                        ],
                        "bhl": [
                          -101.927,
                          31.957
                        ],
                        "formation": "WOLFCAMP A"
                      }
                    ],
                    "summary": true,
                    "eur": true,
                    "bands": true,
                    "band_eur": true,
                    "totals": true,
                    "boe": true,
                    "ip_days": [
                      360,
                      720,
                      1080
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Forecasts, in request order.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForecastResponse"
                },
                "examples": {
                  "explained": {
                    "summary": "Explained",
                    "value": {
                      "pdp": true,
                      "designs": [
                        {
                          "index": 0,
                          "name": "Recent median",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 55.2,
                          "proppant_lb_per_ft": 2716,
                          "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": null,
                                "proppant_lb_per_ft": null
                              },
                              "fluid_bbl_per_ft": 54.5,
                              "proppant_lb_per_ft": 2709.5,
                              "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                            }
                          ]
                        },
                        {
                          "index": 1,
                          "name": "Upsized",
                          "inputs": {
                            "fluid_bbl_per_ft": 60,
                            "proppant_lb_per_ft": 3000
                          },
                          "fluid_bbl_per_ft": 60,
                          "proppant_lb_per_ft": 3000,
                          "completions_source": "input",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": 60,
                                "proppant_lb_per_ft": 3000
                              },
                              "fluid_bbl_per_ft": 60,
                              "proppant_lb_per_ft": 3000,
                              "completions_source": "input"
                            }
                          ]
                        }
                      ],
                      "timings": {
                        "estimate": 1,
                        "subsurface": 1,
                        "spacing": 9,
                        "calc": 8,
                        "forecast": 13,
                        "details": 2,
                        "explain": 74,
                        "total": 110
                      },
                      "wells": [
                        {
                          "index": 0,
                          "key": "DRAWN-0",
                          "label": "Drawn well 1",
                          "inputs": {
                            "shl": [
                              -101.93,
                              31.93
                            ],
                            "bhl": [
                              -101.93,
                              31.957
                            ],
                            "formation": "WOLFCAMP A",
                            "tvd_ft": null,
                            "landing_below_top_ft": null
                          },
                          "lateral_length_ft": 9823,
                          "estimates": {
                            "tvd_ft": 9111,
                            "tvd_source": "WOLFCAMP A top 8,910 ft from the structure grid + 201 ft median landing below top (19 nearby wells)"
                          },
                          "forecasts": [
                            {
                              "design": 0,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "target": "novi_oil",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  217656.1,
                                  325365.3,
                                  397833.2
                                ],
                                "missing": []
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "target": "novi_gas",
                                "unit": "mcf",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  408252.4,
                                  685029.7,
                                  904026.7
                                ],
                                "missing": []
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "target": "novi_water",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  431106.5,
                                  621545,
                                  754211.8
                                ],
                                "missing": []
                              },
                              "checks": {
                                "available": true,
                                "model_num": "M20260930-sample-O-d1",
                                "flagged": false,
                                "out_of_range": [],
                                "missing": [],
                                "unknown_formation": null
                              }
                            },
                            {
                              "design": 1,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "target": "novi_oil",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  227476,
                                  340044.7,
                                  415782.2
                                ],
                                "missing": []
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "target": "novi_gas",
                                "unit": "mcf",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  426671.4,
                                  715936.1,
                                  944813.6
                                ],
                                "missing": []
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "target": "novi_water",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  454134.8,
                                  653166.5,
                                  791818.8
                                ],
                                "missing": []
                              },
                              "checks": {
                                "available": true,
                                "model_num": "M20260930-sample-O-d1",
                                "flagged": false,
                                "out_of_range": [],
                                "missing": [],
                                "unknown_formation": null
                              }
                            }
                          ],
                          "spacing": {
                            "node": {
                              "azimuth": 0.822377,
                              "heel": [
                                -101.93,
                                31.93
                              ],
                              "heel_is_virtual": false,
                              "pad_wells": 0
                            },
                            "neighbors": [
                              {
                                "neighbor": "SB329-10612",
                                "well_name": "WILLINGHAM WEST 36-48 2WB",
                                "operator": "Sample Operator A",
                                "formation": "WOLFCAMP B",
                                "first_prod": "2025-09-09",
                                "heel_lon": -101.930919,
                                "heel_lat": 31.935997,
                                "bhl_lon": -101.930684,
                                "bhl_lat": 31.963259,
                                "position": "stagger",
                                "cone": "leftstaggerbelow",
                                "category": "parent",
                                "signedxy": -256.999718,
                                "signedtvd": 575,
                                "minxy": 256.999718,
                                "mintvd": 575,
                                "mintangent": 629.820494,
                                "overlap": 0.77789,
                                "edge_date": "2026-10-16",
                                "daysonline": 402,
                                "impact_factor": 0.026248,
                                "prior_oil": 233762
                              }
                            ]
                          },
                          "features": {
                            "novi_ip_day": 1,
                            "novi_depletion": null,
                            "novi_net_depletion": null,
                            "novi_spacing_is_child": true,
                            "novi_spacing_parent_count": 4,
                            "novi_spacing_nonparent_count": 0,
                            "novi_spacing_parent_in_formation": "PARENT IN OTHER FORMATION",
                            "novi_spacing_wells_in_radius": 4,
                            "novi_spacing_boundedness_score": 2,
                            "novi_spacing_minxy": 256.999718,
                            "novi_spacing_drainage_area": 1483823.362173,
                            "novi_spacing_lateralcloser_id": null,
                            "novi_spacing_lateralcloser_mintangent": 2863.564213,
                            "novi_unique_key": "DRAWN-0"
                          },
                          "subsurface": {
                            "novi_bvi_avg": 0.051963,
                            "novi_bvi_avg_wolfcamp_a": 0.051963,
                            "novi_bvi_ofnet": 0.059711,
                            "novi_bvi_ofnet_wolfcamp_a": 0.059711,
                            "novi_min_grid_dist": 0,
                            "novi_structuraldepth": -8910.330485,
                            "novi_structuraldepth_wolfcamp_a": -8910.330485,
                            "novi_thickness_avg": 432.538212,
                            "novi_thickness_avg_wolfcamp_a": 432.538212,
                            "novi_thickness_ofnet": 312.778815,
                            "novi_thickness_ofnet_wolfcamp_a": 312.778815
                          },
                          "explanations": [
                            {
                              "design": 0,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "unit": "bbl",
                                "shap": [
                                  {
                                    "ip_day": 360,
                                    "expected_value": 241814.903,
                                    "values": {
                                      "novi_spacing_parent_daysonline": -16873.676,
                                      "novi_spacing_staggercloser_mintangent": -15281.653,
                                      "novi_bvi_avg": 14589.955,
                                      "novi_spacing_parent_mintangent": -14568.499,
                                      "novi_calc_proppant_per_length": 9137.106
                                    }
                                  },
                                  {
                                    "ip_day": 720,
                                    "expected_value": 369542.508,
                                    "values": {
                                      "novi_spacing_parent_daysonline": -28661.458,
                                      "novi_spacing_parent_mintangent": -24677.91,
                                      "novi_spacing_staggercloser_mintangent": -24489.989,
                                      "novi_bvi_avg": 22134.559,
                                      "novi_calc_proppant_per_length": 13852.455
                                    }
                                  },
                                  {
                                    "ip_day": 1080,
                                    "expected_value": 457603.702,
                                    "values": {
                                      "novi_spacing_parent_daysonline": -37559.7,
                                      "novi_spacing_parent_mintangent": -32295.092,
                                      "novi_spacing_staggercloser_mintangent": -31042.257,
                                      "novi_bvi_avg": 27297.11,
                                      "novi_calc_proppant_per_length": 17076.621
                                    }
                                  }
                                ],
                                "other_weight": 0.681845,
                                "contributing_wells": [
                                  {
                                    "key": "SB329-03547",
                                    "weight": 0.016394,
                                    "well_name": "UNDERHILL TRUST 10-22 5WA",
                                    "operator": "Sample Operator A",
                                    "formation": "WOLFCAMP A",
                                    "first_prod": "2019-06-28",
                                    "heel_lon": -101.956996,
                                    "heel_lat": 31.950614,
                                    "bhl_lon": -101.957205,
                                    "bhl_lat": 31.978285
                                  },
                                  {
                                    "key": "SB329-07941",
                                    "weight": 0.016111,
                                    "well_name": "MACKEY 24-36 1WA",
                                    "operator": "Sample Operator A",
                                    "formation": "WOLFCAMP A",
                                    "first_prod": "2023-06-26",
                                    "heel_lon": -101.935715,
                                    "heel_lat": 32.094256,
                                    "bhl_lon": -101.934492,
                                    "bhl_lat": 32.066848
                                  }
                                ]
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "unit": "mcf",
                                "shap": [
                                  {
                                    "ip_day": 360,
                                    "expected_value": 437075.197,
                                    "values": {
                                      "novi_tvd": 31886.786,
                                      "novi_spacing_parent_daysonline": -31874.973,
                                      "novi_spacing_staggercloser_mintangent": -28466.038,
                                      "novi_spacing_parent_mintangent": -27557.484,
                                      "novi_calc_proppant_per_length": 16831.512
                                    }
                                  },
                                  {
                                    "ip_day": 720,
                                    "expected_value": 752418.726,
                                    "values": {
                                      "novi_spacing_parent_daysonline": -61839.803,
                                      "novi_tvd": 54405.171,
                                      "novi_spacing_parent_mintangent": -53303.575,
                                      "novi_spacing_staggercloser_mintangent": -51698.125,
                                      "novi_calc_proppant_per_length": 28707.934
                                    }
                                  },
                                  {
                                    "ip_day": 1080,
                                    "expected_value": 1007989.356,
                                    "values": {
                                      "novi_spacing_parent_daysonline": -88382.167,
                                      "novi_spacing_parent_mintangent": -76068.346,
                                      "novi_tvd": 72512.879,
                                      "novi_spacing_staggercloser_mintangent": -71118.296,
                                      "novi_calc_proppant_per_length": 38254.853
                                    }
                                  }
                                ],
                                "other_weight": 0.697092,
                                "contributing_wells": [
                                  {
                                    "key": "SB329-03547",
                                    "weight": 0.015715,
                                    "well_name": "UNDERHILL TRUST 10-22 5WA",
                                    "operator": "Sample Operator A",
                                    "formation": "WOLFCAMP A",
                                    "first_prod": "2019-06-28",
                                    "heel_lon": -101.956996,
                                    "heel_lat": 31.950614,
                                    "bhl_lon": -101.957205,
                                    "bhl_lat": 31.978285
                                  },
                                  {
                                    "key": "SB329-07941",
                                    "weight": 0.015653,
                                    "well_name": "MACKEY 24-36 1WA",
                                    "operator": "Sample Operator A",
                                    "formation": "WOLFCAMP A",
                                    "first_prod": "2023-06-26",
                                    "heel_lon": -101.935715,
                                    "heel_lat": 32.094256,
                                    "bhl_lon": -101.934492,
                                    "bhl_lat": 32.066848
                                  }
                                ]
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "unit": "bbl",
                                "shap": [
                                  {
                                    "ip_day": 360,
                                    "expected_value": 478622.783,
                                    "values": {
                                      "novi_spacing_parent_daysonline": -29106.032,
                                      "novi_spacing_staggercloser_mintangent": -26224.194,
                                      "novi_spacing_parent_mintangent": -24892.059,
                                      "novi_calc_proppant_per_length": 15660.119,
                                      "novi_calc_fluid_per_length": 13849.881
                                    }
                                  },
                                  {
                                    "ip_day": 720,
                                    "expected_value": 711755.405,
                                    "values": {
                                      "novi_spacing_parent_daysonline": -50284.338,
                                      "novi_spacing_parent_mintangent": -42878.457,
                                      "novi_spacing_staggercloser_mintangent": -42775.772,
                                      "novi_calc_proppant_per_length": 24133.679,
                                      "novi_bvi_avg": 18809.817
                                    }
                                  },
                                  {
                                    "ip_day": 1080,
                                    "expected_value": 878172.27,
                                    "values": {
                                      "novi_spacing_parent_daysonline": -66832.932,
                                      "novi_spacing_parent_mintangent": -56906.996,
                                      "novi_spacing_staggercloser_mintangent": -54970.618,
                                      "novi_calc_proppant_per_length": 30133.485,
                                      "novi_bvi_avg": 23507.804
                                    }
                                  }
                                ],
                                "other_weight": 0.708663,
                                "contributing_wells": [
                                  {
                                    "key": "SB329-03547",
                                    "weight": 0.014324,
                                    "well_name": "UNDERHILL TRUST 10-22 5WA",
                                    "operator": "Sample Operator A",
                                    "formation": "WOLFCAMP A",
                                    "first_prod": "2019-06-28",
                                    "heel_lon": -101.956996,
                                    "heel_lat": 31.950614,
                                    "bhl_lon": -101.957205,
                                    "bhl_lat": 31.978285
                                  },
                                  {
                                    "key": "SB329-07941",
                                    "weight": 0.014306,
                                    "well_name": "MACKEY 24-36 1WA",
                                    "operator": "Sample Operator A",
                                    "formation": "WOLFCAMP A",
                                    "first_prod": "2023-06-26",
                                    "heel_lon": -101.935715,
                                    "heel_lat": 32.094256,
                                    "bhl_lon": -101.934492,
                                    "bhl_lat": 32.066848
                                  }
                                ]
                              }
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "summary": {
                    "summary": "summary: true, ip_days 360, 720, 1080",
                    "value": {
                      "pdp": true,
                      "designs": [
                        {
                          "index": 0,
                          "name": "Recent median",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 55.2,
                          "proppant_lb_per_ft": 2716,
                          "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": null,
                                "proppant_lb_per_ft": null
                              },
                              "fluid_bbl_per_ft": 54.5,
                              "proppant_lb_per_ft": 2709.5,
                              "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                            }
                          ]
                        },
                        {
                          "index": 1,
                          "name": "Upsized",
                          "inputs": {
                            "fluid_bbl_per_ft": 60,
                            "proppant_lb_per_ft": 3000
                          },
                          "fluid_bbl_per_ft": 60,
                          "proppant_lb_per_ft": 3000,
                          "completions_source": "input",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": 60,
                                "proppant_lb_per_ft": 3000
                              },
                              "fluid_bbl_per_ft": 60,
                              "proppant_lb_per_ft": 3000,
                              "completions_source": "input"
                            }
                          ]
                        }
                      ],
                      "wells": [
                        {
                          "index": 0,
                          "key": "DRAWN-0",
                          "label": "Drawn well 1",
                          "inputs": {
                            "shl": [
                              -101.93,
                              31.93
                            ],
                            "bhl": [
                              -101.93,
                              31.957
                            ],
                            "formation": "WOLFCAMP A",
                            "tvd_ft": null,
                            "landing_below_top_ft": null
                          },
                          "lateral_length_ft": 9823,
                          "estimates": {
                            "tvd_ft": 9111,
                            "tvd_source": "WOLFCAMP A top 8,910 ft from the structure grid + 201 ft median landing below top (19 nearby wells)"
                          },
                          "forecasts": [
                            {
                              "design": 0,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "target": "novi_oil",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  217624,
                                  325320.8,
                                  397782
                                ],
                                "missing": []
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "target": "novi_gas",
                                "unit": "mcf",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  408192.5,
                                  684938.2,
                                  903914.8
                                ],
                                "missing": []
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "target": "novi_water",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  431052.9,
                                  621469.6,
                                  754124
                                ],
                                "missing": []
                              },
                              "checks": {
                                "available": true,
                                "model_num": "M20260930-sample-O-d1",
                                "flagged": false,
                                "out_of_range": [],
                                "missing": [],
                                "unknown_formation": null
                              }
                            },
                            {
                              "design": 1,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "target": "novi_oil",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  227442.5,
                                  339998.2,
                                  415728.6
                                ],
                                "missing": []
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "target": "novi_gas",
                                "unit": "mcf",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  426608.9,
                                  715840.4,
                                  944696.6
                                ],
                                "missing": []
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "target": "novi_water",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  454078.8,
                                  653087.7,
                                  791727
                                ],
                                "missing": []
                              },
                              "checks": {
                                "available": true,
                                "model_num": "M20260930-sample-O-d1",
                                "flagged": false,
                                "out_of_range": [],
                                "missing": [],
                                "unknown_formation": null
                              }
                            }
                          ],
                          "spacing": {
                            "node": {
                              "azimuth": 0.822377,
                              "heel": [
                                -101.93,
                                31.93
                              ],
                              "heel_is_virtual": false,
                              "pad_wells": 0
                            },
                            "neighbor_count": 4
                          }
                        }
                      ],
                      "timings": {
                        "estimate": 3,
                        "subsurface": 1,
                        "spacing": 10,
                        "calc": 5,
                        "forecast": 3,
                        "details": 5,
                        "total": 29
                      }
                    }
                  },
                  "eur": {
                    "summary": "eur: true, summary, ip_days 360, 720, 1080",
                    "value": {
                      "pdp": true,
                      "designs": [
                        {
                          "index": 0,
                          "name": "Recent median",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 55.2,
                          "proppant_lb_per_ft": 2716,
                          "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": null,
                                "proppant_lb_per_ft": null
                              },
                              "fluid_bbl_per_ft": 54.5,
                              "proppant_lb_per_ft": 2709.5,
                              "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                            }
                          ]
                        },
                        {
                          "index": 1,
                          "name": "Upsized",
                          "inputs": {
                            "fluid_bbl_per_ft": 60,
                            "proppant_lb_per_ft": 3000
                          },
                          "fluid_bbl_per_ft": 60,
                          "proppant_lb_per_ft": 3000,
                          "completions_source": "input",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": 60,
                                "proppant_lb_per_ft": 3000
                              },
                              "fluid_bbl_per_ft": 60,
                              "proppant_lb_per_ft": 3000,
                              "completions_source": "input"
                            }
                          ]
                        }
                      ],
                      "decline": {
                        "eur_years": 50,
                        "terminal_decline": 0.06,
                        "b_min": 0.5,
                        "b_max": 2.5
                      },
                      "wells": [
                        {
                          "index": 0,
                          "key": "DRAWN-0",
                          "label": "Drawn well 1",
                          "inputs": {
                            "shl": [
                              -101.93,
                              31.93
                            ],
                            "bhl": [
                              -101.93,
                              31.957
                            ],
                            "formation": "WOLFCAMP A",
                            "tvd_ft": null,
                            "landing_below_top_ft": null
                          },
                          "lateral_length_ft": 9823,
                          "estimates": {
                            "tvd_ft": 9111,
                            "tvd_source": "WOLFCAMP A top 8,910 ft from the structure grid + 201 ft median landing below top (19 nearby wells)"
                          },
                          "forecasts": [
                            {
                              "design": 0,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "target": "novi_oil",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  217624,
                                  325320.8,
                                  397782
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 953794.229666,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1111.689674,
                                    "d": 0.005389,
                                    "b": 1.055556,
                                    "terminal_year": 14.82924
                                  }
                                }
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "target": "novi_gas",
                                "unit": "mcf",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  408192.5,
                                  684938.2,
                                  903914.8
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 3519482.657914,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1629.498832,
                                    "d": 0.003162,
                                    "b": 1.833333,
                                    "terminal_year": 8.3428
                                  }
                                }
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "target": "novi_water",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  431052.9,
                                  621469.6,
                                  754124
                                ],
                                "missing": []
                              },
                              "checks": {
                                "available": true,
                                "model_num": "M20260930-sample-O-d1",
                                "flagged": false,
                                "out_of_range": [],
                                "missing": [],
                                "unknown_formation": null
                              }
                            },
                            {
                              "design": 1,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "target": "novi_oil",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  227442.5,
                                  339998.2,
                                  415728.6
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 996826.402911,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1161.845716,
                                    "d": 0.005389,
                                    "b": 1.055556,
                                    "terminal_year": 14.82924
                                  }
                                }
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "target": "novi_gas",
                                "unit": "mcf",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  426608.9,
                                  715840.4,
                                  944696.6
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 3678271.902976,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1703.017473,
                                    "d": 0.003162,
                                    "b": 1.833333,
                                    "terminal_year": 8.3428
                                  }
                                }
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "target": "novi_water",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  454078.8,
                                  653087.7,
                                  791727
                                ],
                                "missing": []
                              },
                              "checks": {
                                "available": true,
                                "model_num": "M20260930-sample-O-d1",
                                "flagged": false,
                                "out_of_range": [],
                                "missing": [],
                                "unknown_formation": null
                              }
                            }
                          ],
                          "spacing": {
                            "node": {
                              "azimuth": 0.822377,
                              "heel": [
                                -101.93,
                                31.93
                              ],
                              "heel_is_virtual": false,
                              "pad_wells": 0
                            },
                            "neighbor_count": 4
                          }
                        }
                      ],
                      "timings": {
                        "estimate": 11,
                        "subsurface": 2,
                        "spacing": 5,
                        "calc": 10,
                        "forecast": 30,
                        "details": 12,
                        "total": 73
                      }
                    }
                  },
                  "eurStreams": {
                    "summary": "eur: true, per-stream decline (gas 8%)",
                    "value": {
                      "pdp": true,
                      "designs": [
                        {
                          "index": 0,
                          "name": "Design 1",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 55.2,
                          "proppant_lb_per_ft": 2716,
                          "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": null,
                                "proppant_lb_per_ft": null
                              },
                              "fluid_bbl_per_ft": 54.5,
                              "proppant_lb_per_ft": 2709.5,
                              "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                            }
                          ]
                        }
                      ],
                      "decline": {
                        "eur_years": 30,
                        "terminal_decline": 0.06,
                        "b_min": 0.5,
                        "b_max": 2.5,
                        "oil": {
                          "terminal_decline": 0.06,
                          "b_min": 0.5,
                          "b_max": 2.5
                        },
                        "gas": {
                          "terminal_decline": 0.08,
                          "b_min": 0.5,
                          "b_max": 2.5
                        }
                      },
                      "wells": [
                        {
                          "index": 0,
                          "key": "DRAWN-0",
                          "label": "Drawn well 1",
                          "inputs": {
                            "shl": [
                              -101.93,
                              31.93
                            ],
                            "bhl": [
                              -101.93,
                              31.957
                            ],
                            "formation": "WOLFCAMP A",
                            "tvd_ft": null,
                            "landing_below_top_ft": null
                          },
                          "lateral_length_ft": 9823,
                          "estimates": {
                            "tvd_ft": 9111,
                            "tvd_source": "WOLFCAMP A top 8,910 ft from the structure grid + 201 ft median landing below top (19 nearby wells)"
                          },
                          "forecasts": [
                            {
                              "design": 0,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "target": "novi_oil",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  217624,
                                  325320.8,
                                  397782
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 885120.683713,
                                  "days": 10950,
                                  "arps": {
                                    "q_i": 1111.689674,
                                    "d": 0.005389,
                                    "b": 1.055556,
                                    "terminal_year": 14.82924
                                  }
                                }
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "target": "novi_gas",
                                "unit": "mcf",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  408192.5,
                                  684938.2,
                                  903914.8
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 2892883.34994,
                                  "days": 10950,
                                  "arps": {
                                    "q_i": 1629.498832,
                                    "d": 0.003162,
                                    "b": 1.833333,
                                    "terminal_year": 6.069095
                                  }
                                }
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "target": "novi_water",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  431052.9,
                                  621469.6,
                                  754124
                                ],
                                "missing": []
                              },
                              "checks": {
                                "available": true,
                                "model_num": "M20260930-sample-O-d1",
                                "flagged": false,
                                "out_of_range": [],
                                "missing": [],
                                "unknown_formation": null
                              }
                            }
                          ],
                          "spacing": {
                            "node": {
                              "azimuth": 0.822377,
                              "heel": [
                                -101.93,
                                31.93
                              ],
                              "heel_is_virtual": false,
                              "pad_wells": 0
                            },
                            "neighbor_count": 4
                          }
                        }
                      ],
                      "timings": {
                        "estimate": 4,
                        "subsurface": 0,
                        "spacing": 4,
                        "calc": 5,
                        "forecast": 6,
                        "details": 5,
                        "total": 25
                      }
                    }
                  },
                  "bands": {
                    "summary": "bands: true, band_eur, til_date 2027-01-01",
                    "value": {
                      "pdp": true,
                      "designs": [
                        {
                          "index": 0,
                          "name": "Design 1",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 55.2,
                          "proppant_lb_per_ft": 2716,
                          "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": null,
                                "proppant_lb_per_ft": null
                              },
                              "fluid_bbl_per_ft": 54.5,
                              "proppant_lb_per_ft": 2709.5,
                              "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                            }
                          ]
                        }
                      ],
                      "decline": {
                        "eur_years": 50,
                        "terminal_decline": 0.06,
                        "b_min": 0.5,
                        "b_max": 2.5
                      },
                      "bands": {
                        "percentiles": [
                          10,
                          90
                        ],
                        "method": "Novi's predrill bands (split conformal)",
                        "eur": true
                      },
                      "wells": [
                        {
                          "index": 0,
                          "key": "DRAWN-0",
                          "label": "Drawn well 1",
                          "inputs": {
                            "shl": [
                              -101.93,
                              31.93
                            ],
                            "bhl": [
                              -101.93,
                              31.957
                            ],
                            "formation": "WOLFCAMP A",
                            "tvd_ft": null,
                            "landing_below_top_ft": null,
                            "til_date": "2027-01-01"
                          },
                          "lateral_length_ft": 9823,
                          "estimates": {
                            "tvd_ft": 9111,
                            "tvd_source": "WOLFCAMP A top 8,910 ft from the structure grid + 201 ft median landing below top (19 nearby wells)"
                          },
                          "forecasts": [
                            {
                              "design": 0,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "target": "novi_oil",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  215368.3,
                                  322196.5,
                                  394184.1
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 946820.446343,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1104.93994,
                                    "d": 0.005389,
                                    "b": 1.055556,
                                    "terminal_year": 14.82924
                                  }
                                },
                                "bands": {
                                  "p10": {
                                    "values": [
                                      150757.8,
                                      225537.5,
                                      275928.9
                                    ],
                                    "eur": {
                                      "value": 662775.404039,
                                      "days": 18240,
                                      "arps": {
                                        "q_i": 773.460081,
                                        "d": 0.005389,
                                        "b": 1.055556,
                                        "terminal_year": 14.82924
                                      }
                                    }
                                  },
                                  "p90": {
                                    "values": [
                                      301515.6,
                                      451075,
                                      551857.7
                                    ],
                                    "eur": {
                                      "value": 1325540.092092,
                                      "days": 18240,
                                      "arps": {
                                        "q_i": 1546.898936,
                                        "d": 0.005389,
                                        "b": 1.055556,
                                        "terminal_year": 14.82924
                                      }
                                    }
                                  }
                                }
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "target": "novi_gas",
                                "unit": "mcf",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  403986.9,
                                  678510.1,
                                  896058
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 3503668.103714,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1612.233475,
                                    "d": 0.003162,
                                    "b": 1.847222,
                                    "terminal_year": 8.280072
                                  }
                                },
                                "bands": {
                                  "p10": {
                                    "values": [
                                      282790.9,
                                      474957.1,
                                      627240.6
                                    ],
                                    "eur": {
                                      "value": 2452566.100453,
                                      "days": 18240,
                                      "arps": {
                                        "q_i": 1128.562461,
                                        "d": 0.003162,
                                        "b": 1.847222,
                                        "terminal_year": 8.280072
                                      }
                                    }
                                  },
                                  "p90": {
                                    "values": [
                                      565581.7,
                                      949914.1,
                                      1254481.1
                                    ],
                                    "eur": {
                                      "value": 4905116.379437,
                                      "days": 18240,
                                      "arps": {
                                        "q_i": 2257.115201,
                                        "d": 0.003162,
                                        "b": 1.847222,
                                        "terminal_year": 8.280072
                                      }
                                    }
                                  }
                                }
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "target": "novi_water",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  427288.3,
                                  616170.7,
                                  747958.5
                                ],
                                "missing": [],
                                "bands": {
                                  "p10": {
                                    "values": [
                                      299101.8,
                                      431319.5,
                                      523571
                                    ]
                                  },
                                  "p90": {
                                    "values": [
                                      598203.6,
                                      862639,
                                      1047142
                                    ]
                                  }
                                }
                              },
                              "checks": {
                                "available": true,
                                "model_num": "M20260930-sample-O-d1",
                                "flagged": false,
                                "out_of_range": [],
                                "missing": [],
                                "unknown_formation": null
                              }
                            }
                          ],
                          "spacing": {
                            "node": {
                              "azimuth": 0.822377,
                              "heel": [
                                -101.93,
                                31.93
                              ],
                              "heel_is_virtual": false,
                              "pad_wells": 0
                            },
                            "neighbor_count": 4
                          }
                        }
                      ],
                      "timings": {
                        "estimate": 4,
                        "subsurface": 1,
                        "spacing": 7,
                        "calc": 5,
                        "forecast": 10,
                        "details": 10,
                        "total": 46
                      }
                    }
                  },
                  "boe": {
                    "summary": "totals and boe: each well's BOE with bands and EUR, and the totals' BOE",
                    "value": {
                      "pdp": true,
                      "designs": [
                        {
                          "index": 0,
                          "name": "Design 1",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 55.2,
                          "proppant_lb_per_ft": 2716,
                          "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": null,
                                "proppant_lb_per_ft": null
                              },
                              "fluid_bbl_per_ft": 54.5,
                              "proppant_lb_per_ft": 2709.5,
                              "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                            }
                          ]
                        }
                      ],
                      "decline": {
                        "eur_years": 50,
                        "terminal_decline": 0.06,
                        "b_min": 0.5,
                        "b_max": 2.5
                      },
                      "bands": {
                        "percentiles": [
                          10,
                          90
                        ],
                        "method": "Novi's predrill bands (split conformal)",
                        "eur": true
                      },
                      "wells": [
                        {
                          "index": 0,
                          "key": "DRAWN-0",
                          "label": "Drawn well 1",
                          "inputs": {
                            "shl": [
                              -101.93,
                              31.93
                            ],
                            "bhl": [
                              -101.93,
                              31.957
                            ],
                            "formation": "WOLFCAMP A",
                            "tvd_ft": null,
                            "landing_below_top_ft": null
                          },
                          "lateral_length_ft": 9823,
                          "estimates": {
                            "tvd_ft": 9111,
                            "tvd_source": "WOLFCAMP A top 8,910 ft from the structure grid + 201 ft median landing below top (19 nearby wells)"
                          },
                          "forecasts": [
                            {
                              "design": 0,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "target": "novi_oil",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  200553.2,
                                  298722.3,
                                  364587.1
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 867874.693843,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1045.431511,
                                    "d": 0.005623,
                                    "b": 1.055556,
                                    "terminal_year": 14.849347
                                  }
                                },
                                "bands": {
                                  "p10": {
                                    "values": [
                                      140387.2,
                                      209105.6,
                                      255211
                                    ],
                                    "eur": {
                                      "value": 607522.895627,
                                      "days": 18240,
                                      "arps": {
                                        "q_i": 731.824034,
                                        "d": 0.005623,
                                        "b": 1.055556,
                                        "terminal_year": 14.849347
                                      }
                                    }
                                  },
                                  "p90": {
                                    "values": [
                                      280774.5,
                                      418211.3,
                                      510421.9
                                    ],
                                    "eur": {
                                      "value": 1215024.531381,
                                      "days": 18240,
                                      "arps": {
                                        "q_i": 1463.604115,
                                        "d": 0.005623,
                                        "b": 1.055556,
                                        "terminal_year": 14.849347
                                      }
                                    }
                                  }
                                }
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "target": "novi_gas",
                                "unit": "mcf",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  375902.6,
                                  628147.1,
                                  827186
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 3196715.044887,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1525.332016,
                                    "d": 0.003371,
                                    "b": 1.833333,
                                    "terminal_year": 8.372079
                                  }
                                },
                                "bands": {
                                  "p10": {
                                    "values": [
                                      263131.8,
                                      439703,
                                      579030.2
                                    ],
                                    "eur": {
                                      "value": 2237706.784797,
                                      "days": 18240,
                                      "arps": {
                                        "q_i": 1067.736437,
                                        "d": 0.003371,
                                        "b": 1.833333,
                                        "terminal_year": 8.372079
                                      }
                                    }
                                  },
                                  "p90": {
                                    "values": [
                                      526263.7,
                                      879406,
                                      1158060.4
                                    ],
                                    "eur": {
                                      "value": 4475397.936155,
                                      "days": 18240,
                                      "arps": {
                                        "q_i": 2135.46281,
                                        "d": 0.003371,
                                        "b": 1.833333,
                                        "terminal_year": 8.372079
                                      }
                                    }
                                  }
                                }
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "target": "novi_water",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  402244.8,
                                  575815.4,
                                  696393.2
                                ],
                                "missing": [],
                                "bands": {
                                  "p10": {
                                    "values": [
                                      281571.4,
                                      403070.8,
                                      487475.2
                                    ]
                                  },
                                  "p90": {
                                    "values": [
                                      563142.8,
                                      806141.5,
                                      974950.4
                                    ]
                                  }
                                }
                              },
                              "boe": {
                                "unit": "BOE",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  263203.6,
                                  403413.5,
                                  502451.4
                                ],
                                "eur": {
                                  "value": 1400660.5,
                                  "days": 18240
                                },
                                "bands": {
                                  "p10": {
                                    "values": [
                                      184242.5,
                                      282389.4,
                                      351716
                                    ],
                                    "eur": {
                                      "value": 980474,
                                      "days": 18240
                                    }
                                  },
                                  "p90": {
                                    "values": [
                                      368485.1,
                                      564779,
                                      703432
                                    ],
                                    "eur": {
                                      "value": 1960924.2,
                                      "days": 18240
                                    }
                                  }
                                }
                              },
                              "checks": {
                                "available": true,
                                "model_num": "M20260930-sample-O-d1",
                                "flagged": false,
                                "out_of_range": [],
                                "missing": [],
                                "unknown_formation": null
                              }
                            }
                          ],
                          "spacing": {
                            "node": {
                              "azimuth": 0.822377,
                              "heel": [
                                -101.93,
                                31.93
                              ],
                              "heel_is_virtual": false,
                              "pad_wells": 0
                            },
                            "neighbor_count": 5
                          }
                        },
                        {
                          "index": 1,
                          "key": "DRAWN-1",
                          "label": "Drawn well 2",
                          "inputs": {
                            "shl": [
                              -101.927,
                              31.93
                            ],
                            "bhl": [
                              -101.927,
                              31.957
                            ],
                            "formation": "WOLFCAMP A",
                            "tvd_ft": null,
                            "landing_below_top_ft": null
                          },
                          "lateral_length_ft": 9823,
                          "estimates": {
                            "tvd_ft": 9110,
                            "tvd_source": "WOLFCAMP A top 8,908 ft from the structure grid + 202 ft median landing below top (18 nearby wells)"
                          },
                          "forecasts": [
                            {
                              "design": 0,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "target": "novi_oil",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  199063.8,
                                  296258.1,
                                  361400.5
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 859017.247716,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1033.652001,
                                    "d": 0.005623,
                                    "b": 1.055556,
                                    "terminal_year": 14.849347
                                  }
                                },
                                "bands": {
                                  "p10": {
                                    "values": [
                                      139344.6,
                                      207380.7,
                                      252980.4
                                    ],
                                    "eur": {
                                      "value": 601314.239388,
                                      "days": 18240,
                                      "arps": {
                                        "q_i": 723.560796,
                                        "d": 0.005623,
                                        "b": 1.055556,
                                        "terminal_year": 14.849347
                                      }
                                    }
                                  },
                                  "p90": {
                                    "values": [
                                      278689.3,
                                      414761.4,
                                      505960.7
                                    ],
                                    "eur": {
                                      "value": 1202628.378776,
                                      "days": 18240,
                                      "arps": {
                                        "q_i": 1447.121592,
                                        "d": 0.005623,
                                        "b": 1.055556,
                                        "terminal_year": 14.849347
                                      }
                                    }
                                  }
                                }
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "target": "novi_gas",
                                "unit": "mcf",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  372931.2,
                                  622576.6,
                                  819361.7
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 3159434.39428,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1522.938463,
                                    "d": 0.003444,
                                    "b": 1.833333,
                                    "terminal_year": 8.38143
                                  }
                                },
                                "bands": {
                                  "p10": {
                                    "values": [
                                      261051.8,
                                      435803.6,
                                      573553.2
                                    ],
                                    "eur": {
                                      "value": 2211594.713709,
                                      "days": 18240,
                                      "arps": {
                                        "q_i": 1066.050824,
                                        "d": 0.003444,
                                        "b": 1.833333,
                                        "terminal_year": 8.38143
                                      }
                                    }
                                  },
                                  "p90": {
                                    "values": [
                                      522103.7,
                                      871607.2,
                                      1147106.4
                                    ],
                                    "eur": {
                                      "value": 4423205.047897,
                                      "days": 18240,
                                      "arps": {
                                        "q_i": 2132.111814,
                                        "d": 0.003444,
                                        "b": 1.833333,
                                        "terminal_year": 8.38143
                                      }
                                    }
                                  }
                                }
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "target": "novi_water",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  399734.9,
                                  571592,
                                  690854.6
                                ],
                                "missing": [],
                                "bands": {
                                  "p10": {
                                    "values": [
                                      279814.4,
                                      400114.4,
                                      483598.2
                                    ]
                                  },
                                  "p90": {
                                    "values": [
                                      559628.9,
                                      800228.7,
                                      967196.4
                                    ]
                                  }
                                }
                              },
                              "boe": {
                                "unit": "BOE",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  261219,
                                  400020.9,
                                  497960.8
                                ],
                                "eur": {
                                  "value": 1385589.6,
                                  "days": 18240
                                },
                                "bands": {
                                  "p10": {
                                    "values": [
                                      182853.2,
                                      280014.6,
                                      348572.6
                                    ],
                                    "eur": {
                                      "value": 969913.4,
                                      "days": 18240
                                    }
                                  },
                                  "p90": {
                                    "values": [
                                      365706.6,
                                      560029.3,
                                      697145.1
                                    ],
                                    "eur": {
                                      "value": 1939829.2,
                                      "days": 18240
                                    }
                                  }
                                }
                              },
                              "checks": {
                                "available": true,
                                "model_num": "M20260930-sample-O-d1",
                                "flagged": false,
                                "out_of_range": [],
                                "missing": [],
                                "unknown_formation": null
                              }
                            }
                          ],
                          "spacing": {
                            "node": {
                              "azimuth": 0.820832,
                              "heel": [
                                -101.927,
                                31.93
                              ],
                              "heel_is_virtual": false,
                              "pad_wells": 0
                            },
                            "neighbor_count": 7
                          }
                        }
                      ],
                      "totals": [
                        {
                          "design": 0,
                          "wells_with_forecast": 2,
                          "wells_flagged": 0,
                          "forecast": {
                            "oil": {
                              "model_num": "M20260930-sample-O-d1",
                              "target": "novi_oil",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                399617,
                                594980.4,
                                725987.6
                              ],
                              "missing": [],
                              "bands": {
                                "p10": {
                                  "values": [
                                    279731.8,
                                    416486.3,
                                    508191.4
                                  ]
                                },
                                "p90": {
                                  "values": [
                                    559463.8,
                                    832972.7,
                                    1016382.6
                                  ]
                                }
                              }
                            },
                            "gas": {
                              "model_num": "M20260930-sample-G-d1",
                              "target": "novi_gas",
                              "unit": "mcf",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                748833.8,
                                1250723.7,
                                1646547.7
                              ],
                              "missing": [],
                              "bands": {
                                "p10": {
                                  "values": [
                                    524183.6,
                                    875506.6,
                                    1152583.4
                                  ]
                                },
                                "p90": {
                                  "values": [
                                    1048367.4,
                                    1751013.2,
                                    2305166.8
                                  ]
                                }
                              }
                            },
                            "water": {
                              "model_num": "M20260930-sample-W-d1",
                              "target": "novi_water",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                801979.7,
                                1147407.4,
                                1387247.8
                              ],
                              "missing": [],
                              "bands": {
                                "p10": {
                                  "values": [
                                    561385.8,
                                    803185.2,
                                    971073.4
                                  ]
                                },
                                "p90": {
                                  "values": [
                                    1122771.7,
                                    1606370.2,
                                    1942146.8
                                  ]
                                }
                              }
                            },
                            "boe": {
                              "unit": "BOE",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                524422.6,
                                803434.4,
                                1000412.2
                              ],
                              "wells": 2,
                              "bands": {
                                "p10": {
                                  "values": [
                                    367095.7,
                                    562404,
                                    700288.6
                                  ]
                                },
                                "p90": {
                                  "values": [
                                    734191.7,
                                    1124808.3,
                                    1400577.1
                                  ]
                                }
                              }
                            }
                          },
                          "eur": {
                            "oil": {
                              "value": 1726891.9,
                              "days": 18240,
                              "wells": 2,
                              "p10": {
                                "value": 1208837.1,
                                "wells": 2
                              },
                              "p90": {
                                "value": 2417652.9,
                                "wells": 2
                              }
                            },
                            "gas": {
                              "value": 6356149.4,
                              "days": 18240,
                              "wells": 2,
                              "p10": {
                                "value": 4449301.5,
                                "wells": 2
                              },
                              "p90": {
                                "value": 8898603,
                                "wells": 2
                              }
                            },
                            "boe": {
                              "value": 2786250.2,
                              "wells": 2,
                              "p10": {
                                "value": 1950387.4,
                                "wells": 2
                              },
                              "p90": {
                                "value": 3900753.4,
                                "wells": 2
                              }
                            }
                          }
                        }
                      ],
                      "timings": {
                        "estimate": 7,
                        "subsurface": 2,
                        "spacing": 18,
                        "calc": 14,
                        "forecast": 29,
                        "details": 7,
                        "total": 104
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "With async: true: the job, running (or, replaying an Idempotency-Key, as it is now).",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForecastJob"
                },
                "example": {
                  "id": "3f6d1a52-8b0e-4c47-9a61-2d5e7c9b0f14",
                  "status": "running",
                  "created_at": "2026-11-02T18:04:11.000Z",
                  "finished_at": null,
                  "seconds": 0.4,
                  "result": null,
                  "error": null,
                  "links": {
                    "self": "/api/v1/forecasts/3f6d1a52-8b0e-4c47-9a61-2d5e7c9b0f14"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "With async: true: the Idempotency-Key was already used with a different body, or 50 async forecasts are already running (with `Retry-After: 1`).",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "502": {
            "$ref": "#/components/responses/WorkerFailed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/forecasts/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Forecast job id from POST /forecasts with async: true.",
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "example": "3f6d1a52-8b0e-4c47-9a61-2d5e7c9b0f14"
        }
      ],
      "get": {
        "operationId": "getForecast",
        "tags": [
          "Forecasts"
        ],
        "summary": "Get an async forecast",
        "description": "An async forecast: its status and, once done, `result` (the body POST /forecasts answers without `async`) or, once failed, `error`.\n\n**Waiting.** While running it answers with `Retry-After: 1`; send `wait` instead of polling. A finished job carries an `ETag`; send it as `If-None-Match` for a 304.\n\n**Scope.** Any model set's job answers without `model_set`. Jobs are kept an hour after they finish (POST /forecasts says where); an unknown, expired or other-tenant id is a 404, as is a job on a set scoped to other tenants.",
        "parameters": [
          {
            "name": "wait",
            "in": "query",
            "description": "Use this instead of polling: on a running forecast, the answer is held until it finishes, or this many seconds pass.\n\nWhole seconds, 1 to 25 (400 otherwise). The answer is what a GET without `wait` would get when the wait ends, `Retry-After` included; a finished job answers at once. A client that disconnects ends the wait.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The forecast job.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForecastJob"
                },
                "examples": {
                  "running": {
                    "summary": "Running",
                    "value": {
                      "id": "3f6d1a52-8b0e-4c47-9a61-2d5e7c9b0f14",
                      "status": "running",
                      "created_at": "2026-11-02T18:04:11.000Z",
                      "finished_at": null,
                      "seconds": 0.4,
                      "result": null,
                      "error": null,
                      "links": {
                        "self": "/api/v1/forecasts/3f6d1a52-8b0e-4c47-9a61-2d5e7c9b0f14"
                      }
                    }
                  },
                  "done": {
                    "summary": "Done, from the summary example",
                    "value": {
                      "id": "3f6d1a52-8b0e-4c47-9a61-2d5e7c9b0f14",
                      "status": "done",
                      "created_at": "2026-11-02T18:04:11.000Z",
                      "finished_at": "2026-11-02T18:04:13.000Z",
                      "seconds": 2.1,
                      "result": {
                        "pdp": true,
                        "designs": [
                          {
                            "index": 0,
                            "name": "Recent median",
                            "inputs": {
                              "fluid_bbl_per_ft": null,
                              "proppant_lb_per_ft": null
                            },
                            "fluid_bbl_per_ft": 55.2,
                            "proppant_lb_per_ft": 2716,
                            "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                            "formations": [
                              {
                                "formation": "WOLFCAMP A",
                                "inputs": {
                                  "fluid_bbl_per_ft": null,
                                  "proppant_lb_per_ft": null
                                },
                                "fluid_bbl_per_ft": 54.5,
                                "proppant_lb_per_ft": 2709.5,
                                "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                              }
                            ]
                          },
                          {
                            "index": 1,
                            "name": "Upsized",
                            "inputs": {
                              "fluid_bbl_per_ft": 60,
                              "proppant_lb_per_ft": 3000
                            },
                            "fluid_bbl_per_ft": 60,
                            "proppant_lb_per_ft": 3000,
                            "completions_source": "input",
                            "formations": [
                              {
                                "formation": "WOLFCAMP A",
                                "inputs": {
                                  "fluid_bbl_per_ft": 60,
                                  "proppant_lb_per_ft": 3000
                                },
                                "fluid_bbl_per_ft": 60,
                                "proppant_lb_per_ft": 3000,
                                "completions_source": "input"
                              }
                            ]
                          }
                        ],
                        "wells": [
                          {
                            "index": 0,
                            "key": "DRAWN-0",
                            "label": "Drawn well 1",
                            "inputs": {
                              "shl": [
                                -101.93,
                                31.93
                              ],
                              "bhl": [
                                -101.93,
                                31.957
                              ],
                              "formation": "WOLFCAMP A",
                              "tvd_ft": null,
                              "landing_below_top_ft": null
                            },
                            "lateral_length_ft": 9823,
                            "estimates": {
                              "tvd_ft": 9111,
                              "tvd_source": "WOLFCAMP A top 8,910 ft from the structure grid + 201 ft median landing below top (19 nearby wells)"
                            },
                            "forecasts": [
                              {
                                "design": 0,
                                "oil": {
                                  "model_num": "M20260930-sample-O-d1",
                                  "target": "novi_oil",
                                  "unit": "bbl",
                                  "ip_days": [
                                    360,
                                    720,
                                    1080
                                  ],
                                  "values": [
                                    217624,
                                    325320.8,
                                    397782
                                  ],
                                  "missing": []
                                },
                                "gas": {
                                  "model_num": "M20260930-sample-G-d1",
                                  "target": "novi_gas",
                                  "unit": "mcf",
                                  "ip_days": [
                                    360,
                                    720,
                                    1080
                                  ],
                                  "values": [
                                    408192.5,
                                    684938.2,
                                    903914.8
                                  ],
                                  "missing": []
                                },
                                "water": {
                                  "model_num": "M20260930-sample-W-d1",
                                  "target": "novi_water",
                                  "unit": "bbl",
                                  "ip_days": [
                                    360,
                                    720,
                                    1080
                                  ],
                                  "values": [
                                    431052.9,
                                    621469.6,
                                    754124
                                  ],
                                  "missing": []
                                },
                                "checks": {
                                  "available": true,
                                  "model_num": "M20260930-sample-O-d1",
                                  "flagged": false,
                                  "out_of_range": [],
                                  "missing": [],
                                  "unknown_formation": null
                                }
                              },
                              {
                                "design": 1,
                                "oil": {
                                  "model_num": "M20260930-sample-O-d1",
                                  "target": "novi_oil",
                                  "unit": "bbl",
                                  "ip_days": [
                                    360,
                                    720,
                                    1080
                                  ],
                                  "values": [
                                    227442.5,
                                    339998.2,
                                    415728.6
                                  ],
                                  "missing": []
                                },
                                "gas": {
                                  "model_num": "M20260930-sample-G-d1",
                                  "target": "novi_gas",
                                  "unit": "mcf",
                                  "ip_days": [
                                    360,
                                    720,
                                    1080
                                  ],
                                  "values": [
                                    426608.9,
                                    715840.4,
                                    944696.6
                                  ],
                                  "missing": []
                                },
                                "water": {
                                  "model_num": "M20260930-sample-W-d1",
                                  "target": "novi_water",
                                  "unit": "bbl",
                                  "ip_days": [
                                    360,
                                    720,
                                    1080
                                  ],
                                  "values": [
                                    454078.8,
                                    653087.7,
                                    791727
                                  ],
                                  "missing": []
                                },
                                "checks": {
                                  "available": true,
                                  "model_num": "M20260930-sample-O-d1",
                                  "flagged": false,
                                  "out_of_range": [],
                                  "missing": [],
                                  "unknown_formation": null
                                }
                              }
                            ],
                            "spacing": {
                              "node": {
                                "azimuth": 0.822377,
                                "heel": [
                                  -101.93,
                                  31.93
                                ],
                                "heel_is_virtual": false,
                                "pad_wells": 0
                              },
                              "neighbor_count": 4
                            }
                          }
                        ],
                        "timings": {
                          "estimate": 3,
                          "subsurface": 1,
                          "spacing": 10,
                          "calc": 5,
                          "forecast": 3,
                          "details": 5,
                          "total": 29
                        }
                      },
                      "error": null,
                      "links": {
                        "self": "/api/v1/forecasts/3f6d1a52-8b0e-4c47-9a61-2d5e7c9b0f14"
                      }
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/declines": {
      "post": {
        "operationId": "fitDeclines",
        "tags": [
          "Forecasts"
        ],
        "summary": "Fit EUR to curves you have",
        "description": "EUR for up to 500 cumulative curves (one stream each, as a forecast returned them), with the same fit and settings as `eur: true` on POST /forecasts, so nothing is re-forecast.\n\n**Results.** Each curve gets `{value, days, arps}` or `{error}`, in request order. When `decline` sets per-stream settings (`oil` or `gas`), every series names its `stream` and is fit with that stream's settings.\n\n**Queue and errors.** Interactive work: it doesn't queue behind plans' EUR. It answers 503 when GET /dataset `eur.available` is false.",
        "requestBody": {
          "required": true,
          "description": "Curves, 1 to 500, and optional settings.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeclinesRequest"
              },
              "example": {
                "series": [
                  {
                    "key": "scenario-1/well-1/oil",
                    "ip_days": [
                      30,
                      60,
                      90,
                      120,
                      150,
                      180,
                      210,
                      240,
                      270,
                      300,
                      330,
                      360,
                      390,
                      420,
                      450,
                      480,
                      510,
                      540,
                      570,
                      600,
                      630,
                      660,
                      690,
                      720,
                      750,
                      780,
                      810,
                      840,
                      870,
                      900,
                      930,
                      960,
                      990,
                      1020,
                      1050,
                      1080
                    ],
                    "values": [
                      24305.2,
                      51179.8,
                      75035.6,
                      96465.9,
                      115926.1,
                      133753.7,
                      150206,
                      165483.8,
                      179746.5,
                      193123.1,
                      205719.7,
                      217624,
                      228909.9,
                      239640,
                      249868,
                      259639.8,
                      268995.7,
                      277970.7,
                      286595.5,
                      294897.3,
                      302900.3,
                      310626,
                      318093.8,
                      325320.8,
                      332322.8,
                      339114,
                      345707.2,
                      352114.1,
                      358345.5,
                      364411.1,
                      370320,
                      376080.4,
                      381700,
                      387185.9,
                      392544.5,
                      397782
                    ]
                  },
                  {
                    "key": "scenario-1/well-1/gas",
                    "ip_days": [
                      30,
                      60,
                      90,
                      120,
                      150,
                      180,
                      210,
                      240,
                      270,
                      300,
                      330,
                      360,
                      390,
                      420,
                      450,
                      480,
                      510,
                      540,
                      570,
                      600,
                      630,
                      660,
                      690,
                      720,
                      750,
                      780,
                      810,
                      840,
                      870,
                      900,
                      930,
                      960,
                      990,
                      1020,
                      1050,
                      1080
                    ],
                    "values": [
                      37802.2,
                      81528.8,
                      122143.3,
                      160192.4,
                      196116.7,
                      230243.9,
                      262824.1,
                      294053.4,
                      324088.2,
                      353055.8,
                      381061.2,
                      408192.5,
                      434523.9,
                      460119.2,
                      485033.3,
                      509314,
                      533003.3,
                      556138.3,
                      578752.1,
                      600874.1,
                      622530.8,
                      643746.2,
                      664542.1,
                      684938.2,
                      704952.8,
                      724602.4,
                      743902.4,
                      762867,
                      781509.4,
                      799841.8,
                      817875.5,
                      835621.2,
                      853088.9,
                      870288,
                      887227.2,
                      903914.8
                    ]
                  }
                ],
                "decline": {
                  "eur_years": 30
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One EUR per curve, in request order.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeclinesResponse"
                },
                "examples": {
                  "shared": {
                    "summary": "Shared settings",
                    "value": {
                      "decline": {
                        "eur_years": 30,
                        "terminal_decline": 0.06,
                        "b_min": 0.5,
                        "b_max": 2.5
                      },
                      "results": [
                        {
                          "key": "scenario-1/well-1/oil",
                          "eur": {
                            "value": 885120.683713,
                            "days": 10950,
                            "arps": {
                              "q_i": 1111.689674,
                              "d": 0.005389,
                              "b": 1.055556,
                              "terminal_year": 14.82924
                            }
                          }
                        },
                        {
                          "key": "scenario-1/well-1/gas",
                          "eur": {
                            "value": 3157576.765976,
                            "days": 10950,
                            "arps": {
                              "q_i": 1629.498832,
                              "d": 0.003162,
                              "b": 1.833333,
                              "terminal_year": 8.3428
                            }
                          }
                        }
                      ]
                    }
                  },
                  "streams": {
                    "summary": "Per-stream settings (gas 8%)",
                    "value": {
                      "decline": {
                        "eur_years": 30,
                        "terminal_decline": 0.06,
                        "b_min": 0.5,
                        "b_max": 2.5,
                        "oil": {
                          "terminal_decline": 0.06,
                          "b_min": 0.5,
                          "b_max": 2.5
                        },
                        "gas": {
                          "terminal_decline": 0.08,
                          "b_min": 0.5,
                          "b_max": 2.5
                        }
                      },
                      "results": [
                        {
                          "key": "scenario-1/well-1/oil",
                          "eur": {
                            "value": 885120.683713,
                            "days": 10950,
                            "arps": {
                              "q_i": 1111.689674,
                              "d": 0.005389,
                              "b": 1.055556,
                              "terminal_year": 14.82924
                            }
                          }
                        },
                        {
                          "key": "scenario-1/well-1/gas",
                          "eur": {
                            "value": 2892883.34994,
                            "days": 10950,
                            "arps": {
                              "q_i": 1629.498832,
                              "d": 0.003162,
                              "b": 1.833333,
                              "terminal_year": 6.069095
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "502": {
            "$ref": "#/components/responses/WorkerFailed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/economics/decks": {
      "get": {
        "operationId": "listEconomicsDecks",
        "tags": [
          "Economics"
        ],
        "summary": "List economics decks",
        "description": "The decks POST /economics can price with (its `deck_id`), the default first. GET /economics/deck describes one in full.\n\n**Decks.** The Illustrative Midland flat-price deck (`prototype-midland-flat`), which the app uses, and the Novi house deck, $70 oil and $3 gas (`house-70-3`). On a model set whose basin is Haynesville, the Illustrative Haynesville gas deck (`illustrative-haynesville-gas`), drafted from public benchmarks and not a Novi default, comes first and is the default.",
        "responses": {
          "200": {
            "description": "The decks, the default first.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EconomicsDeckList"
                },
                "example": {
                  "decks": [
                    {
                      "deck_id": "prototype-midland-flat",
                      "version": 1,
                      "name": "Illustrative Midland flat-price deck",
                      "note": "Illustrative: flat prices and costs for a Midland basin well, with Texas royalty and taxes; not a Novi price deck and not a forward curve."
                    },
                    {
                      "deck_id": "house-70-3",
                      "version": 1,
                      "name": "Novi house deck, $70 oil and $3 gas",
                      "note": "Novi's house deck for quick evaluations: its prices, differentials, royalty, opex and discount rate. Values it lacks, production taxes and capex among them, are the illustrative Midland deck's (source: prototype)."
                    }
                  ]
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/economics/deck": {
      "get": {
        "operationId": "getEconomicsDeck",
        "tags": [
          "Economics"
        ],
        "summary": "Describe the economics deck",
        "description": "A deck POST /economics prices with (the default unless `deck_id` names another): each value with its unit, source, a note on where it comes from and the range an override may take. `deck_id` and `version` name it; the version changes whenever a value does.\n\n**Fields.** `source` is `assumption`, `fit`, `market`, or `prototype` for a value a deck lacks and takes from the illustrative Midland deck. `groups` and `caption` are the lines the app's Economics modal and Economics line show; `conventions` are the two POST /economics can price under, one line each.\n\n**Default decks.** The illustrative Midland flat-price deck, not a Novi price deck: flat prices and opex, Texas royalty and taxes, and an illustrative capex of a fixed cost per well plus costs per lateral foot. On a Haynesville model set, the illustrative Haynesville gas deck: flat public-benchmark prices, gas-weighted costs and Louisiana taxes (applied to East Texas wells too; override `severance_gas` for Texas), each note naming its public source.",
        "parameters": [
          {
            "name": "deck_id",
            "in": "query",
            "description": "The deck to describe, one GET /economics/decks lists for the set; the set's default deck when left out (prototype-midland-flat; illustrative-haynesville-gas on a Haynesville set).",
            "schema": {
              "type": "string",
              "enum": [
                "prototype-midland-flat",
                "house-70-3",
                "illustrative-haynesville-gas"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The deck.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EconomicsDeck"
                },
                "example": {
                  "tax_note": "Texas private minerals",
                  "deck_id": "prototype-midland-flat",
                  "version": 1,
                  "name": "Illustrative Midland flat-price deck",
                  "note": "Illustrative: flat prices and costs for a Midland basin well, with Texas royalty and taxes; not a Novi price deck and not a forward curve.",
                  "values": {
                    "oil_price": {
                      "value": 75,
                      "unit": "$/bbl",
                      "source": "assumption",
                      "note": "WTI, flat for the well's life; illustrative, not a forward curve.",
                      "min": 0,
                      "max": 300
                    },
                    "oil_differential": {
                      "value": 4,
                      "unit": "$/bbl",
                      "source": "assumption",
                      "note": "Taken off WTI; illustrative.",
                      "min": -50,
                      "max": 50
                    },
                    "gas_price": {
                      "value": 3.5,
                      "unit": "$/mcf",
                      "source": "assumption",
                      "note": "Henry Hub, flat, no BTU adjustment; illustrative, not a forward curve.",
                      "min": 0,
                      "max": 50
                    },
                    "gas_differential": {
                      "value": 1,
                      "unit": "$/mcf",
                      "source": "assumption",
                      "note": "Taken off Henry Hub; illustrative.",
                      "min": -10,
                      "max": 10
                    },
                    "ngl_price": {
                      "value": 26,
                      "unit": "$/bbl",
                      "source": "assumption",
                      "note": "NGL barrel, flat; illustrative.",
                      "min": 0,
                      "max": 200
                    },
                    "ngl_yield_bbl_per_mmcf": {
                      "value": 130,
                      "unit": "bbl/MMcf",
                      "source": "assumption",
                      "note": "NGL barrels recovered per MMcf of wellhead gas; illustrative.",
                      "min": 0,
                      "max": 300
                    },
                    "shrink": {
                      "value": 0.8,
                      "unit": "fraction",
                      "source": "assumption",
                      "note": "Share of wellhead gas sold as residue after NGLs come out; illustrative.",
                      "min": 0,
                      "max": 1
                    },
                    "opex_oil": {
                      "value": 5.5,
                      "unit": "$/bbl",
                      "source": "assumption",
                      "note": "Operating cost per barrel of oil, flat; illustrative.",
                      "min": 0,
                      "max": 100
                    },
                    "opex_gas": {
                      "value": 0.5,
                      "unit": "$/mcf",
                      "source": "assumption",
                      "note": "Operating cost per mcf of wellhead gas, flat; illustrative.",
                      "min": 0,
                      "max": 20
                    },
                    "opex_water": {
                      "value": 0.6,
                      "unit": "$/bbl",
                      "source": "assumption",
                      "note": "Water handling per barrel; past the forecast, water follows oil (gas on a set without oil) at the forecast's last-year ratio; illustrative.",
                      "min": 0,
                      "max": 20
                    },
                    "royalty": {
                      "value": 0.25,
                      "unit": "fraction",
                      "source": "assumption",
                      "note": "Royalty on Texas private minerals; illustrative.",
                      "min": 0,
                      "max": 0.5
                    },
                    "severance_oil": {
                      "value": 0.046,
                      "unit": "fraction",
                      "source": "assumption",
                      "note": "Severance on oil revenue, at Texas's oil production tax rate.",
                      "min": 0,
                      "max": 0.5
                    },
                    "severance_gas": {
                      "value": 0.075,
                      "unit": "fraction",
                      "source": "assumption",
                      "note": "Severance on residue gas and NGL revenue, at Texas's gas production tax rate.",
                      "min": 0,
                      "max": 0.5
                    },
                    "ad_valorem": {
                      "value": 0.025,
                      "unit": "fraction",
                      "source": "assumption",
                      "note": "Ad valorem (property) tax, on revenue; illustrative.",
                      "min": 0,
                      "max": 0.2
                    },
                    "capex_per_well": {
                      "value": 2500000,
                      "unit": "$",
                      "source": "fit",
                      "note": "Fixed cost per well, in an illustrative capex formula fit on ten Wolfcamp A base-case locations.",
                      "min": 0,
                      "max": 50000000
                    },
                    "capex_drilling_per_ft": {
                      "value": 150,
                      "unit": "$/ft",
                      "source": "fit",
                      "note": "Drilling per foot of lateral; part of the illustrative capex formula.",
                      "min": 0,
                      "max": 2000
                    },
                    "capex_stimulation_per_ft": {
                      "value": 125,
                      "unit": "$/ft",
                      "source": "fit",
                      "note": "Stimulation per foot of lateral; part of the illustrative capex formula.",
                      "min": 0,
                      "max": 2000
                    },
                    "capex_proppant_per_lb": {
                      "value": 0.08,
                      "unit": "$/lb",
                      "source": "fit",
                      "note": "Proppant per pound pumped (lb/ft × lateral); part of the illustrative capex formula.",
                      "min": 0,
                      "max": 2
                    },
                    "capex_fluid_per_bbl": {
                      "value": 3,
                      "unit": "$/bbl",
                      "source": "fit",
                      "note": "Fluid per barrel pumped (bbl/ft × lateral); part of the illustrative capex formula.",
                      "min": 0,
                      "max": 50
                    },
                    "discount_rate": {
                      "value": 0.25,
                      "unit": "fraction per year",
                      "source": "assumption",
                      "note": "The annual rate NPV discounts at (NPV25 on this deck); illustrative.",
                      "min": 0,
                      "max": 1
                    }
                  },
                  "groups": [
                    {
                      "title": "Prices",
                      "lines": [
                        "Flat: $75/bbl WTI less $4; $3.50/mcf Henry Hub less $1.00,  no BTU adjustment; NGL $26/bbl.",
                        "NGL yield 130 bbl/MMcf; 80% of wellhead gas sold as residue."
                      ]
                    },
                    {
                      "title": "Costs",
                      "lines": [
                        "Opex,  flat: $5.50/bbl oil,  $0.50/mcf gas,  $0.60/bbl water.",
                        "Capex per well,  an assumption: $2.5M fixed,  $150/ft drilling and $125/ft stimulation of lateral,  $0.08/lb proppant,  $3.00/bbl fluid; all spent at month 0."
                      ]
                    },
                    {
                      "title": "Taxes",
                      "lines": [
                        "Texas private minerals: 25% royalty,  severance 4.6% oil and 7.5% gas and NGL,  2.5% ad valorem."
                      ]
                    },
                    {
                      "title": "Discounting",
                      "lines": [
                        "Production starts month 1; the forecast's 3 years,  then each stream declines to its EUR. NPV25 discounts years 2 on at 25% a year; year 1 is undiscounted."
                      ]
                    }
                  ],
                  "caption": "Economics · $75 WTI · $3.50 HH · capex $2.5M + per ft · NPV25",
                  "conventions": {
                    "prototype": "Yearly discounting, the default: NPV leaves year 1 (months 0 to 12) undiscounted and discounts each later year one more year at the annual rate; payback is in fractional months; IRR is the monthly rate annualized as (1+m)^12 − 1; capex is all at month 0.",
                    "fe": "Monthly discounting. Matches Novi's earlier Forecast Engine: the monthly rate m = (1+r)^(1/12) − 1, the cash flow of month n (0 is capex, 1 the first production month) discounted by (1+m)^n; payback in whole months from turn-on; IRR as under yearly discounting. Capex stays all at month 0, since a scenario has no spud or completion dates."
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/economics": {
      "post": {
        "operationId": "priceScenarios",
        "tags": [
          "Economics"
        ],
        "summary": "Price scenarios' economics",
        "description": "Prices scenarios as the Pad Optimizer ranks them: simulated half-cycle economics on each well's forecast and EUR under a deck (GET /economics/deck). Send `scenarios` of wells you have forecast, or a `forecast` for the server to run and price (not both: 400).\n\n**Scenarios.** A scenario is a pad of 1 to 50 wells online together, or a done plan's wells; a request takes 1 to 250 scenarios and at most as many wells as a plan (GET /dataset limits.plan_wells). Without `forecast`, no model worker runs, so it answers in milliseconds.\n\n- Each well sends its lateral, its completion design, its oil, gas and water cumulative curves every 30 days from 30, as POST /forecasts returns them without `ip_days` (other days are a 400), and its oil and gas EUR with the EUR's ip_day.\n- On a plan made with scenarios, a scenario prices one of them, by `scenario` or by wells all in it.\n\n**A forecast.** `forecast` prices drawn wells under several designs in one call, one scenario per design, in design order (see `forecast`).\n\n- Each well is priced as a plan's well is: its formation's completions under the design (else the design's own), its lateral from its ends, its curves and EUR as forecast.\n- A well whose forecast or EUR failed leaves its design's scenario unpriced, and `reason` names it (Drawn well N) and why.\n- The answer adds `forecast` (pdp, wells, the designs as run, the layout) and each scenario's `forecast.design`.\n- Wells × designs count toward the well limit, field paths start `forecast.`, and a worker or layout error answers as POST /forecasts answers it.\n\n**Cash flows.** Monthly: capex at month 0, the forecast's months, then each stream declines exponentially from its last month's rate to its EUR. Water follows oil at the forecast's last-year ratio. Wells are priced on the streams their model set serves: an unserved stream adds nothing, and on a set without oil, water follows gas.\n\n**What you get.** Each scenario's `economics` (capex, IRR as a percent, payback in months, and NPV at the deck's `discount_rate`), or null with a `reason`: the first well without a cash flow (by its `label`, else wells[i]) and why, or the pad's. Each well without a cash flow has its own `reason`.\n\n**Deck and conventions.** `deck_id` picks the deck and `deck` overrides its numbers for this request, each within its range; the answer echoes the effective deck with its id, version and overridden fields. `conventions` picks how NPV and payback are counted: `prototype` (the default and the app's) discounts years 2 on a whole year at a time with fractional payback, and `fe` discounts monthly with whole-month payback, matching Novi's earlier Forecast Engine. IRR is the same under both, and capex is all at month 0, since scenarios have no spud or completion dates.\n\n**Extras.** `include` adds:\n\n- `flows`: each well's and the pad's monthly cash flows; `scenario_flows`: each scenario's only.\n- `totals`: `scenarios`, `priced`, `wells`, `npv` and `capex` over the priced scenarios, and their cash flow by month with flows; IRR and payback don't add. It sums a plan priced in batches; with it, two of one plan's scenarios (different `scenario` names) are a 400.\n- `summary`: each scenario's wells, priced wells, lateral, EUR and completions (ScenarioSummary).\n- `breakeven`: the flat `oil_price` (WTI) and `gas_price` (Henry Hub) at which NPV at `discount_rate` is 0 under the request's `conventions`, every other deck value held, each to within $0.000001 a bbl or mcf.\n\nA breakeven price is null when NPV doesn't cross 0 between that key's min and max (GET /economics/deck), as when oil alone pays a pad back with gas at $0. `breakeven` is null on a scenario without economics, and `totals` has none.",
        "requestBody": {
          "required": true,
          "description": "Scenarios to price, or a forecast to run and price, and optional deck overrides.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EconomicsRequest"
              },
              "examples": {
                "scenario": {
                  "summary": "One scenario",
                  "value": {
                    "scenarios": [
                      {
                        "key": "pad-1/upsized",
                        "wells": [
                          {
                            "label": "Drawn well 1",
                            "lateral_ft": 9850,
                            "design": {
                              "proppant_lb_per_ft": 3000,
                              "fluid_bbl_per_ft": 60
                            },
                            "curves": {
                              "oil": {
                                "ip_days": [
                                  30,
                                  60,
                                  90,
                                  120,
                                  150,
                                  180,
                                  210,
                                  240,
                                  270,
                                  300,
                                  330,
                                  360,
                                  390,
                                  420,
                                  450,
                                  480,
                                  510,
                                  540,
                                  570,
                                  600,
                                  630,
                                  660,
                                  690,
                                  720,
                                  750,
                                  780,
                                  810,
                                  840,
                                  870,
                                  900,
                                  930,
                                  960,
                                  990,
                                  1020,
                                  1050,
                                  1080
                                ],
                                "values": [
                                  23687.7,
                                  49783.6,
                                  72872.3,
                                  93560.2,
                                  112307.5,
                                  129452.9,
                                  145253.3,
                                  159908.1,
                                  173575.1,
                                  186381.7,
                                  198432,
                                  209812.2,
                                  220594.6,
                                  230840.3,
                                  240601.7,
                                  249923.6,
                                  258845.1,
                                  267400.1,
                                  275618.6,
                                  283526.8,
                                  291148.1,
                                  298503.4,
                                  305611.3,
                                  312488.5,
                                  319150.1,
                                  325609.8,
                                  331880,
                                  337971.9,
                                  343896,
                                  349661.5,
                                  355277.2,
                                  360751,
                                  366090.3,
                                  371301.9,
                                  376392,
                                  381366.4
                                ]
                              },
                              "gas": {
                                "ip_days": [
                                  30,
                                  60,
                                  90,
                                  120,
                                  150,
                                  180,
                                  210,
                                  240,
                                  270,
                                  300,
                                  330,
                                  360,
                                  390,
                                  420,
                                  450,
                                  480,
                                  510,
                                  540,
                                  570,
                                  600,
                                  630,
                                  660,
                                  690,
                                  720,
                                  750,
                                  780,
                                  810,
                                  840,
                                  870,
                                  900,
                                  930,
                                  960,
                                  990,
                                  1020,
                                  1050,
                                  1080
                                ],
                                "values": [
                                  36841.4,
                                  79300.3,
                                  118608.3,
                                  155339.1,
                                  189947.1,
                                  222768.3,
                                  254057.4,
                                  284013.2,
                                  312793.6,
                                  340526.6,
                                  367317.5,
                                  393254.2,
                                  418410.8,
                                  442850.6,
                                  466628.2,
                                  489790.9,
                                  512380.2,
                                  534432.8,
                                  555981.1,
                                  577054.2,
                                  597678,
                                  617876.2,
                                  637670,
                                  657078.8,
                                  676120.3,
                                  694810.9,
                                  713165.4,
                                  731197.7,
                                  748920.6,
                                  766346,
                                  783485,
                                  800347.8,
                                  816944.3,
                                  833283.4,
                                  849373.6,
                                  865223.1
                                ]
                              },
                              "water": {
                                "ip_days": [
                                  30,
                                  60,
                                  90,
                                  120,
                                  150,
                                  180,
                                  210,
                                  240,
                                  270,
                                  300,
                                  330,
                                  360,
                                  390,
                                  420,
                                  450,
                                  480,
                                  510,
                                  540,
                                  570,
                                  600,
                                  630,
                                  660,
                                  690,
                                  720,
                                  750,
                                  780,
                                  810,
                                  840,
                                  870,
                                  900,
                                  930,
                                  960,
                                  990,
                                  1020,
                                  1050,
                                  1080
                                ],
                                "values": [
                                  73629.8,
                                  134564.3,
                                  182072.4,
                                  221331.9,
                                  255230.5,
                                  285409.6,
                                  312841.8,
                                  338133,
                                  361682.5,
                                  383768.6,
                                  404596.1,
                                  424322.3,
                                  443072.7,
                                  460950.1,
                                  478040.6,
                                  494417.2,
                                  510143.1,
                                  525272.8,
                                  539854.4,
                                  553929.9,
                                  567536.8,
                                  580708.6,
                                  593475,
                                  605862.8,
                                  617896.2,
                                  629597.2,
                                  640985.6,
                                  652079.5,
                                  662895.5,
                                  673448.7,
                                  683753,
                                  693821.2,
                                  703665.2,
                                  713295.8,
                                  722723.2,
                                  731956.7
                                ]
                              }
                            },
                            "eur": {
                              "oil": 907654.776459,
                              "gas": 3343044.975128
                            },
                            "eur_days": 18240
                          },
                          {
                            "label": "Drawn well 2",
                            "lateral_ft": 9850,
                            "design": {
                              "proppant_lb_per_ft": 3000,
                              "fluid_bbl_per_ft": 60
                            },
                            "curves": {
                              "oil": {
                                "ip_days": [
                                  30,
                                  60,
                                  90,
                                  120,
                                  150,
                                  180,
                                  210,
                                  240,
                                  270,
                                  300,
                                  330,
                                  360,
                                  390,
                                  420,
                                  450,
                                  480,
                                  510,
                                  540,
                                  570,
                                  600,
                                  630,
                                  660,
                                  690,
                                  720,
                                  750,
                                  780,
                                  810,
                                  840,
                                  870,
                                  900,
                                  930,
                                  960,
                                  990,
                                  1020,
                                  1050,
                                  1080
                                ],
                                "values": [
                                  23553.6,
                                  49488.5,
                                  72424.1,
                                  92966.5,
                                  111575.4,
                                  128589,
                                  144263.5,
                                  158797.7,
                                  172349.2,
                                  185044.7,
                                  196988,
                                  208265.1,
                                  218947.9,
                                  229097.5,
                                  238765.7,
                                  247997.4,
                                  256831.4,
                                  265301.4,
                                  273437.3,
                                  281265.1,
                                  288808.3,
                                  296087.4,
                                  303121,
                                  309925.8,
                                  316516.7,
                                  322907.4,
                                  329110.2,
                                  335136.2,
                                  340995.7,
                                  346698.1,
                                  352252.1,
                                  357665.4,
                                  362945.4,
                                  368098.8,
                                  373131.9,
                                  378050.4
                                ]
                              },
                              "gas": {
                                "ip_days": [
                                  30,
                                  60,
                                  90,
                                  120,
                                  150,
                                  180,
                                  210,
                                  240,
                                  270,
                                  300,
                                  330,
                                  360,
                                  390,
                                  420,
                                  450,
                                  480,
                                  510,
                                  540,
                                  570,
                                  600,
                                  630,
                                  660,
                                  690,
                                  720,
                                  750,
                                  780,
                                  810,
                                  840,
                                  870,
                                  900,
                                  930,
                                  960,
                                  990,
                                  1020,
                                  1050,
                                  1080
                                ],
                                "values": [
                                  36619.7,
                                  78801.8,
                                  117835.3,
                                  154294.9,
                                  188635.4,
                                  221192.6,
                                  252221.4,
                                  281920.3,
                                  310447.1,
                                  337929.8,
                                  364473.6,
                                  390166.3,
                                  415081.9,
                                  439283.6,
                                  462826,
                                  485756.4,
                                  508116.2,
                                  529942,
                                  551266.2,
                                  572117.9,
                                  592522.9,
                                  612504.9,
                                  632085,
                                  651282.6,
                                  670115.4,
                                  688599.7,
                                  706750.4,
                                  724581.2,
                                  742104.9,
                                  759333.5,
                                  776277.9,
                                  792948.4,
                                  809354.7,
                                  825505.9,
                                  841410.4,
                                  857076.1
                                ]
                              },
                              "water": {
                                "ip_days": [
                                  30,
                                  60,
                                  90,
                                  120,
                                  150,
                                  180,
                                  210,
                                  240,
                                  270,
                                  300,
                                  330,
                                  360,
                                  390,
                                  420,
                                  450,
                                  480,
                                  510,
                                  540,
                                  570,
                                  600,
                                  630,
                                  660,
                                  690,
                                  720,
                                  750,
                                  780,
                                  810,
                                  840,
                                  870,
                                  900,
                                  930,
                                  960,
                                  990,
                                  1020,
                                  1050,
                                  1080
                                ],
                                "values": [
                                  73410.6,
                                  134076.7,
                                  181327.8,
                                  220342.9,
                                  254008.7,
                                  283965.6,
                                  311184.9,
                                  336271.8,
                                  359624.6,
                                  381521.1,
                                  402165.3,
                                  421714.2,
                                  440292.8,
                                  458003.4,
                                  474931.9,
                                  491151.1,
                                  506723.6,
                                  521704,
                                  536139.9,
                                  550073.3,
                                  563541.5,
                                  576577.6,
                                  589211.4,
                                  601469.6,
                                  613376.1,
                                  624952.7,
                                  636219.3,
                                  647193.8,
                                  657892.7,
                                  668331,
                                  678522.6,
                                  688480.2,
                                  698215.4,
                                  707739.2,
                                  717061.6,
                                  726191.9
                                ]
                              }
                            },
                            "eur": {
                              "oil": 898424.591784,
                              "gas": 3304133.453865
                            },
                            "eur_days": 18240
                          }
                        ]
                      }
                    ]
                  }
                },
                "forecast": {
                  "summary": "Two drawn wells under two designs, with summary",
                  "value": {
                    "forecast": {
                      "wells": [
                        {
                          "shl": [
                            -101.93,
                            31.93
                          ],
                          "bhl": [
                            -101.93,
                            31.957
                          ],
                          "formation": "WOLFCAMP A"
                        },
                        {
                          "shl": [
                            -101.927,
                            31.93
                          ],
                          "bhl": [
                            -101.927,
                            31.957
                          ],
                          "formation": "WOLFCAMP A"
                        }
                      ],
                      "designs": [
                        {
                          "name": "Recent median"
                        },
                        {
                          "name": "Upsized",
                          "fluid_bbl_per_ft": 60,
                          "proppant_lb_per_ft": 3000
                        }
                      ]
                    },
                    "include": [
                      "summary"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One result per scenario, in request order.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EconomicsResponse"
                },
                "examples": {
                  "scenario": {
                    "summary": "One scenario",
                    "value": {
                      "deck": {
                        "deck_id": "prototype-midland-flat",
                        "version": 1,
                        "name": "Illustrative Midland flat-price deck",
                        "overrides": [],
                        "discount_rate": 0.25,
                        "values": {
                          "oil_price": 75,
                          "oil_differential": 4,
                          "gas_price": 3.5,
                          "gas_differential": 1,
                          "ngl_price": 26,
                          "ngl_yield_bbl_per_mmcf": 130,
                          "shrink": 0.8,
                          "opex_oil": 5.5,
                          "opex_gas": 0.5,
                          "opex_water": 0.6,
                          "royalty": 0.25,
                          "severance_oil": 0.046,
                          "severance_gas": 0.075,
                          "ad_valorem": 0.025,
                          "capex_per_well": 2500000,
                          "capex_drilling_per_ft": 150,
                          "capex_stimulation_per_ft": 125,
                          "capex_proppant_per_lb": 0.08,
                          "capex_fluid_per_bbl": 3,
                          "discount_rate": 0.25
                        }
                      },
                      "conventions": "prototype",
                      "scenarios": [
                        {
                          "key": "pad-1/upsized",
                          "economics": {
                            "capex": 18691500,
                            "irr_pct": 129.051191,
                            "payback_months": 10.556193,
                            "npv": 25495446.998099
                          },
                          "reason": null,
                          "wells": [
                            {
                              "reason": null
                            },
                            {
                              "reason": null
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "flows": {
                    "summary": "Oil at $65, with flows",
                    "value": {
                      "deck": {
                        "deck_id": "prototype-midland-flat",
                        "version": 1,
                        "name": "Illustrative Midland flat-price deck",
                        "overrides": [
                          "oil_price"
                        ],
                        "discount_rate": 0.25,
                        "values": {
                          "oil_price": 65,
                          "oil_differential": 4,
                          "gas_price": 3.5,
                          "gas_differential": 1,
                          "ngl_price": 26,
                          "ngl_yield_bbl_per_mmcf": 130,
                          "shrink": 0.8,
                          "opex_oil": 5.5,
                          "opex_gas": 0.5,
                          "opex_water": 0.6,
                          "royalty": 0.25,
                          "severance_oil": 0.046,
                          "severance_gas": 0.075,
                          "ad_valorem": 0.025,
                          "capex_per_well": 2500000,
                          "capex_drilling_per_ft": 150,
                          "capex_stimulation_per_ft": 125,
                          "capex_proppant_per_lb": 0.08,
                          "capex_fluid_per_bbl": 3,
                          "discount_rate": 0.25
                        }
                      },
                      "conventions": "prototype",
                      "scenarios": [
                        {
                          "key": "pad-1/upsized",
                          "economics": {
                            "capex": 18691500,
                            "irr_pct": 91.930566,
                            "payback_months": 13.358668,
                            "npv": 19426249.206071
                          },
                          "reason": null,
                          "wells": [
                            {
                              "reason": null,
                              "flows": [
                                -9345750,
                                949202.314908,
                                1063687.511829,
                                950422.591041,
                                858321.637622,
                                782966.873246,
                                720232.307499,
                                667232.967492,
                                621882.773614,
                                582635.836601,
                                548344.445771,
                                518118.077687,
                                491267.339518
                              ]
                            },
                            {
                              "reason": null,
                              "flows": [
                                -9345750,
                                943668.914048,
                                1057013.906102,
                                944042.094628,
                                852225.553281,
                                777138.529422,
                                714653.149196,
                                661878.464471,
                                616730.171538,
                                577678.01069,
                                543555.757971,
                                513487.577783,
                                486787.482732
                              ]
                            }
                          ],
                          "flows": [
                            -18691500,
                            1892871.228956,
                            2120701.417931,
                            1894464.68567,
                            1710547.190904,
                            1560105.402668,
                            1434885.456695,
                            1329111.431963,
                            1238612.945152,
                            1160313.847291,
                            1091900.203742,
                            1031605.65547,
                            978054.822251
                          ]
                        }
                      ]
                    }
                  },
                  "fe": {
                    "summary": "Novi house deck, fe conventions (monthly discounting)",
                    "value": {
                      "deck": {
                        "deck_id": "house-70-3",
                        "version": 1,
                        "name": "Novi house deck, $70 oil and $3 gas",
                        "overrides": [],
                        "discount_rate": 0.1,
                        "values": {
                          "oil_price": 70,
                          "oil_differential": 6.5,
                          "gas_price": 3,
                          "gas_differential": 0.65,
                          "ngl_price": 24.5,
                          "ngl_yield_bbl_per_mmcf": 130,
                          "shrink": 0.8,
                          "opex_oil": 5,
                          "opex_gas": 0.4,
                          "opex_water": 0.6,
                          "royalty": 0.22,
                          "severance_oil": 0.046,
                          "severance_gas": 0.075,
                          "ad_valorem": 0.025,
                          "capex_per_well": 2500000,
                          "capex_drilling_per_ft": 150,
                          "capex_stimulation_per_ft": 125,
                          "capex_proppant_per_lb": 0.08,
                          "capex_fluid_per_bbl": 3,
                          "discount_rate": 0.1
                        }
                      },
                      "conventions": "fe",
                      "scenarios": [
                        {
                          "key": "pad-1/upsized",
                          "economics": {
                            "capex": 18691500,
                            "irr_pct": 112.545366,
                            "payback_months": 12,
                            "npv": 35758437.039695
                          },
                          "reason": null,
                          "wells": [
                            {
                              "reason": null
                            },
                            {
                              "reason": null
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "totals": {
                    "summary": "A pad priced in two batches, with scenario_flows and totals, cut to 13 months",
                    "value": {
                      "deck": {
                        "deck_id": "prototype-midland-flat",
                        "version": 1,
                        "name": "Illustrative Midland flat-price deck",
                        "overrides": [],
                        "discount_rate": 0.25,
                        "values": {
                          "oil_price": 75,
                          "oil_differential": 4,
                          "gas_price": 3.5,
                          "gas_differential": 1,
                          "ngl_price": 26,
                          "ngl_yield_bbl_per_mmcf": 130,
                          "shrink": 0.8,
                          "opex_oil": 5.5,
                          "opex_gas": 0.5,
                          "opex_water": 0.6,
                          "royalty": 0.25,
                          "severance_oil": 0.046,
                          "severance_gas": 0.075,
                          "ad_valorem": 0.025,
                          "capex_per_well": 2500000,
                          "capex_drilling_per_ft": 150,
                          "capex_stimulation_per_ft": 125,
                          "capex_proppant_per_lb": 0.08,
                          "capex_fluid_per_bbl": 3,
                          "discount_rate": 0.25
                        }
                      },
                      "conventions": "prototype",
                      "scenarios": [
                        {
                          "key": "batch-1",
                          "economics": {
                            "capex": 9345750,
                            "irr_pct": 130.100605,
                            "payback_months": 10.505992,
                            "npv": 12842801.828799
                          },
                          "reason": null,
                          "wells": [
                            {
                              "reason": null
                            }
                          ],
                          "flows": [
                            -9345750,
                            1113932.831597,
                            1245158.088493,
                            1110988.461984,
                            1002186.512845,
                            913345.120708,
                            839477.546828,
                            777128.87301,
                            723814.84597,
                            677705.342227,
                            637431.276894,
                            601948.001107,
                            570441.383304
                          ]
                        },
                        {
                          "key": "batch-2",
                          "economics": {
                            "capex": 9345750,
                            "irr_pct": 127.762756,
                            "payback_months": 10.620951,
                            "npv": 12636922.677497
                          },
                          "reason": null,
                          "wells": [
                            {
                              "reason": null
                            }
                          ],
                          "flows": [
                            -9345750,
                            1107435.856735,
                            1237336.712332,
                            1103511.411289,
                            995060.101917,
                            906536.294692,
                            832960.113523,
                            770880.909359,
                            717806.44454,
                            671927.175199,
                            631857.465977,
                            596565.263247,
                            565232.466307
                          ]
                        }
                      ],
                      "totals": {
                        "scenarios": 2,
                        "priced": 2,
                        "wells": 2,
                        "npv": 25479724.506296,
                        "capex": 18691500,
                        "flows": [
                          -18691500,
                          2221368.688332,
                          2482494.800825,
                          2214499.873273,
                          1997246.614762,
                          1819881.4154,
                          1672437.66035,
                          1548009.782369,
                          1441621.29051,
                          1349632.517427,
                          1269288.742871,
                          1198513.264354,
                          1135673.849611
                        ]
                      }
                    }
                  },
                  "forecast": {
                    "summary": "The forecast request: one scenario per design, with summary",
                    "value": {
                      "deck": {
                        "deck_id": "prototype-midland-flat",
                        "version": 1,
                        "name": "Illustrative Midland flat-price deck",
                        "overrides": [],
                        "discount_rate": 0.25,
                        "values": {
                          "oil_price": 75,
                          "oil_differential": 4,
                          "gas_price": 3.5,
                          "gas_differential": 1,
                          "ngl_price": 26,
                          "ngl_yield_bbl_per_mmcf": 130,
                          "shrink": 0.8,
                          "opex_oil": 5.5,
                          "opex_gas": 0.5,
                          "opex_water": 0.6,
                          "royalty": 0.25,
                          "severance_oil": 0.046,
                          "severance_gas": 0.075,
                          "ad_valorem": 0.025,
                          "capex_per_well": 2500000,
                          "capex_drilling_per_ft": 150,
                          "capex_stimulation_per_ft": 125,
                          "capex_proppant_per_lb": 0.08,
                          "capex_fluid_per_bbl": 3,
                          "discount_rate": 0.25
                        }
                      },
                      "conventions": "prototype",
                      "forecast": {
                        "pdp": true,
                        "wells": 2,
                        "designs": [
                          {
                            "index": 0,
                            "name": "Recent median",
                            "inputs": {
                              "fluid_bbl_per_ft": null,
                              "proppant_lb_per_ft": null
                            },
                            "fluid_bbl_per_ft": 55.2,
                            "proppant_lb_per_ft": 2716,
                            "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                            "formations": [
                              {
                                "formation": "WOLFCAMP A",
                                "inputs": {
                                  "fluid_bbl_per_ft": null,
                                  "proppant_lb_per_ft": null
                                },
                                "fluid_bbl_per_ft": 54.5,
                                "proppant_lb_per_ft": 2709.5,
                                "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                              }
                            ]
                          },
                          {
                            "index": 1,
                            "name": "Upsized",
                            "inputs": {
                              "fluid_bbl_per_ft": 60,
                              "proppant_lb_per_ft": 3000
                            },
                            "fluid_bbl_per_ft": 60,
                            "proppant_lb_per_ft": 3000,
                            "completions_source": "input",
                            "formations": [
                              {
                                "formation": "WOLFCAMP A",
                                "inputs": {
                                  "fluid_bbl_per_ft": 60,
                                  "proppant_lb_per_ft": 3000
                                },
                                "fluid_bbl_per_ft": 60,
                                "proppant_lb_per_ft": 3000,
                                "completions_source": "input"
                              }
                            ]
                          }
                        ]
                      },
                      "scenarios": [
                        {
                          "forecast": {
                            "design": 0
                          },
                          "economics": {
                            "capex": 17908622,
                            "irr_pct": 128.435682,
                            "payback_months": 10.589886,
                            "npv": 24339868.362228
                          },
                          "reason": null,
                          "wells": [
                            {
                              "reason": null
                            },
                            {
                              "reason": null
                            }
                          ],
                          "summary": {
                            "wells": 2,
                            "priced": 2,
                            "total_lateral_ft": 19700,
                            "eur": {
                              "oil": 1726891.9,
                              "gas": 6356149.4,
                              "boe": 2786250.2,
                              "wells": 2
                            },
                            "completions": [
                              {
                                "formation": "WOLFCAMP A",
                                "wells": 2,
                                "proppant_lb_per_ft": 2709.5,
                                "fluid_bbl_per_ft": 54.5
                              }
                            ]
                          }
                        },
                        {
                          "forecast": {
                            "design": 1
                          },
                          "economics": {
                            "capex": 18691500,
                            "irr_pct": 128.767738,
                            "payback_months": 10.572514,
                            "npv": 25458960.068849
                          },
                          "reason": null,
                          "wells": [
                            {
                              "reason": null
                            },
                            {
                              "reason": null
                            }
                          ],
                          "summary": {
                            "wells": 2,
                            "priced": 2,
                            "total_lateral_ft": 19700,
                            "eur": {
                              "oil": 1804822.6,
                              "gas": 6642901.1,
                              "boe": 2911972.8,
                              "wells": 2
                            },
                            "completions": [
                              {
                                "formation": "WOLFCAMP A",
                                "wells": 2,
                                "proppant_lb_per_ft": 3000,
                                "fluid_bbl_per_ft": 60
                              }
                            ]
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "502": {
            "$ref": "#/components/responses/WorkerFailed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/plans": {
      "post": {
        "operationId": "createPlan",
        "tags": [
          "Plans"
        ],
        "summary": "Start a plan",
        "description": "Starts a development plan as a background job and answers 202 with its `Location`. A plan runs up to GET /dataset `limits.plan_wells` forecasts (wells × completion designs): 10,000 by default, so 5,000 wells with two designs.\n\n**What you send.** `wells`, a `layout` the server lays out, or up to 100 `layouts`, their wells one after another (each echoed in `layouts` with `first`, its first well's plan index). `from_plan` runs a done plan's request again on the set's current models; `assumption_set` fills fields the body leaves out. The body may be up to 64 MB.\n\n**Waiting.** GET /plans/{id}?wait=25 until `status` is `done` or `error`; each answer waits for the status to change. With an `Idempotency-Key`, a retry returns the plan the first request started.\n\n**Options.** Each is described on its field.\n\n- `eur: true` adds an `eur` step: every forecast carries `eur`, totals add each stream's EUR sum and count, and the export's forecast.csv adds EUR columns.\n- `bands: true` gives every forecast its P10/P90 bands, summed in totals; with `band_eur: true`, totals add `p10` and `p90` EUR.\n- With TIL dates (`til_date` on a well, pad, layout, scenario or the plan), wells space as parents and children in date order, and totals add `by_date`, each stream by calendar month.\n- `per_well_errors: true` fails a well that can't be placed on its own.\n- `dry_run: true` checks and counts the plan (PlanDryRun) without starting it. Wells aren't placed until a plan runs; POST /tvd-estimates gives the TVD a plan would estimate.\n\n**Scenarios.** With a `scenario` on every well, or on every layout, up to 20 alternatives run in one plan, each scenario's wells spacing against only each other and existing wells. `totals` come per scenario and design, GET /plans/{id}/stats takes `group_by=scenario` or `scenario`, an export or economics reference takes one scenario at a time, and GET /plans/{id}/export answers 409.\n\n**Depletion chain.** A dated plan chains depletion by default where GET /dataset `depletion_chain.available` is true: a planned well's P50 feeds the neighbor-production features of the later-month plan wells it is a parent of, and the plan echoes `depletion_chain`. See `depletion_chain`.\n\n**Chunks and queue.** Wells run in spatial chunks of about 1,000, each with the plan wells within the spacing radius around it. Plans queue, oldest first, for a server task with room: a task runs at most 80,000 forecasts in plans at once, or `limits.plan_wells` + 10,000 where that is more. A queued plan reads `running`, with `progress`, `done` and every `steps` count 0, until a task takes it; a create never answers 409 for server load.\n\n**Limits.** `limits.plan_wells` is at most 100,000. Once a caller has a plan queued or running, a new plan that would take their unfinished forecasts (wells × designs, across model sets) past GET /dataset `limits.plan_unfinished_forecasts` answers 429 with `Retry-After`; a caller with nothing unfinished is always accepted. The caller is the request's user, or the server without sign-in. Plans being deleted don't count, and a dry run is never refused.\n\n**Server tasks.** Where a plan runs and is kept.\n\n- With a state store and Redis, any task takes queued plans and answers GET, `wait`, PATCH and DELETE for any plan. A DELETE stops a plan running on another task after its chunks in flight.\n- A plan running on another task answers GET with its progress; with `include=wells` it lists no wells until done (with `Retry-After: 1`), and a `sort` is a 409 until then.\n- A plan with `callback_url` runs on the task that took it, and may start before older queued plans.\n- With a state store, a finished plan is read back from the store. Without one, plans don't survive a restart (GET /health `uptime_s` starts from 0): keep a deadline and create the plan again on a 404.\n\n**Callbacks.** With `callback_url`, the server POSTs `{\"type\": \"plan.done\" | \"plan.failed\", \"plan\": <the plan, as GET /plans/{id} returns it without include, less callbacks>}` once the plan is done or fails; a plan deleted while running sends nothing.\n\n- It goes as an export's callback does (POST /exports): the same host allowlist (GET /export-formats `callbacks`, whose `events` list only export events; 400 while callbacks are off), https and public addresses only.\n- 3 retries after 2 s, 15 s and 60 s, with the same `X-Export-Event`, `X-Export-Delivery` and `X-Export-Signature` headers, plus `X-Plan-Id`.\n- A plan takes one URL; its `callbacks` shows the delivery, the URL as its origin.\n- The payload has the totals but no wells: page them with GET /plans/{id}?include=wells, or export the plan with a `callback_url` of its own and download it within the export's time to live.\n\n**Retention.** With a state store, an unsaved plan is kept for the server's scratch period after it is made (90 days unless the server sets another; `storage.expires_at` says when) and deleted within a minute of `expires_at`; a saved plan is kept until deleted. Saving clears `expires_at`; unsaving starts a new scratch period. A deleted plan is gone from the API at once, its shares revoked and its attached documents deleted.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Plan wells, a layout or layouts, and options.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlanRequest"
              },
              "examples": {
                "wells": {
                  "summary": "Wells",
                  "value": {
                    "name": "Section 36 infill",
                    "wells": [
                      {
                        "shl": [
                          -101.93,
                          31.93
                        ],
                        "bhl": [
                          -101.93,
                          31.957
                        ],
                        "formation": "WOLFCAMP A"
                      },
                      {
                        "shl": [
                          -101.927,
                          31.93
                        ],
                        "bhl": [
                          -101.927,
                          31.957
                        ],
                        "formation": "WOLFCAMP A",
                        "tvd_ft": 9150
                      }
                    ],
                    "designs": [
                      {
                        "name": "Recent median"
                      },
                      {
                        "name": "Upsized",
                        "fluid_bbl_per_ft": 60,
                        "proppant_lb_per_ft": 3000
                      }
                    ],
                    "pdp": true,
                    "eur": true
                  }
                },
                "layouts": {
                  "summary": "Two layouts: a polygon, and a holed unit in two benches",
                  "value": {
                    "name": "Two units",
                    "layouts": [
                      {
                        "polygon": [
                          [
                            -101.95,
                            31.93
                          ],
                          [
                            -101.93,
                            31.93
                          ],
                          [
                            -101.93,
                            31.95
                          ],
                          [
                            -101.95,
                            31.95
                          ]
                        ],
                        "spacing_ft": 880,
                        "formation": "WOLFCAMP A"
                      },
                      {
                        "area": {
                          "type": "Polygon",
                          "coordinates": [
                            [
                              [
                                -101.95,
                                31.93
                              ],
                              [
                                -101.93,
                                31.93
                              ],
                              [
                                -101.93,
                                31.96
                              ],
                              [
                                -101.95,
                                31.96
                              ],
                              [
                                -101.95,
                                31.93
                              ]
                            ],
                            [
                              [
                                -101.945,
                                31.945
                              ],
                              [
                                -101.94,
                                31.945
                              ],
                              [
                                -101.94,
                                31.94
                              ],
                              [
                                -101.945,
                                31.94
                              ],
                              [
                                -101.945,
                                31.945
                              ]
                            ]
                          ]
                        },
                        "setback_ft": 330,
                        "setback_end_ft": 467,
                        "min_lateral_ft": 4346,
                        "benches": [
                          {
                            "wells_per_section": 6,
                            "formation": "WOLFCAMP A"
                          },
                          {
                            "spacing_ft": 1320,
                            "offset_ft": 440,
                            "formation": "WOLFCAMP B",
                            "landing_below_top_ft": 40
                          }
                        ],
                        "standoff_ft": 150,
                        "wells_per_pad": 4
                      }
                    ],
                    "eur": true
                  }
                },
                "callback": {
                  "summary": "Wells, POSTed to a receiver once done",
                  "value": {
                    "name": "Section 36 infill",
                    "wells": [
                      {
                        "shl": [
                          -101.93,
                          31.93
                        ],
                        "bhl": [
                          -101.93,
                          31.957
                        ],
                        "formation": "WOLFCAMP A"
                      },
                      {
                        "shl": [
                          -101.927,
                          31.93
                        ],
                        "bhl": [
                          -101.927,
                          31.957
                        ],
                        "formation": "WOLFCAMP A",
                        "tvd_ft": 9150
                      }
                    ],
                    "eur": true,
                    "callback_url": "https://hooks.example.com/novi/plans"
                  }
                },
                "chain": {
                  "summary": "Four wells TIL four months apart, depletion_chain: true",
                  "value": {
                    "name": "Section 36 schedule",
                    "wells": [
                      {
                        "shl": [
                          -101.93,
                          31.93
                        ],
                        "bhl": [
                          -101.93,
                          31.957
                        ],
                        "formation": "WOLFCAMP A",
                        "til_date": "2027-01-15"
                      },
                      {
                        "shl": [
                          -101.9279,
                          31.93
                        ],
                        "bhl": [
                          -101.9279,
                          31.957
                        ],
                        "formation": "WOLFCAMP A",
                        "til_date": "2027-05-15"
                      },
                      {
                        "shl": [
                          -101.9258,
                          31.93
                        ],
                        "bhl": [
                          -101.9258,
                          31.957
                        ],
                        "formation": "WOLFCAMP A",
                        "til_date": "2027-09-15"
                      },
                      {
                        "shl": [
                          -101.9237,
                          31.93
                        ],
                        "bhl": [
                          -101.9237,
                          31.957
                        ],
                        "formation": "WOLFCAMP A",
                        "til_date": "2028-01-15"
                      }
                    ],
                    "eur": true,
                    "depletion_chain": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "With dry_run: true: the plan a create would start, counted; nothing was started.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanDryRun"
                },
                "examples": {
                  "wells": {
                    "summary": "The wells example with dry_run: true",
                    "value": {
                      "dry_run": true,
                      "wells": 2,
                      "designs": 2,
                      "forecasts": 4
                    }
                  },
                  "layouts": {
                    "summary": "The two layouts example with dry_run: true",
                    "value": {
                      "dry_run": true,
                      "wells": 16,
                      "designs": 1,
                      "forecasts": 16,
                      "layouts": [
                        {
                          "first": 0,
                          "count": 8,
                          "azimuth_deg": 0,
                          "spacing_ft": 880,
                          "lateral_length_ft": null,
                          "formation": "WOLFCAMP A"
                        },
                        {
                          "first": 8,
                          "count": 8,
                          "azimuth_deg": 0,
                          "lateral_length_ft": null,
                          "setback_ft": 330,
                          "setback_end_ft": 467,
                          "min_lateral_ft": 4346,
                          "standoff_ft": 150,
                          "standoff_wells": 18,
                          "wells_per_pad": 4,
                          "wells_per_section": 10,
                          "pads": [
                            [
                              8,
                              9,
                              12,
                              13
                            ],
                            [
                              10,
                              11,
                              14,
                              15
                            ]
                          ],
                          "benches": [
                            {
                              "spacing_ft": 880,
                              "wells_per_section": 6,
                              "offset_ft": 0,
                              "formation": "WOLFCAMP A",
                              "count": 4,
                              "wells": [
                                8,
                                9,
                                10,
                                11
                              ]
                            },
                            {
                              "spacing_ft": 1320,
                              "wells_per_section": 4,
                              "offset_ft": 440,
                              "formation": "WOLFCAMP B",
                              "count": 4,
                              "wells": [
                                12,
                                13,
                                14,
                                15
                              ]
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "The plan, running (or, replaying an Idempotency-Key, as it is now).",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Plan"
                },
                "example": {
                  "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                  "name": "Section 36 infill",
                  "status": "running",
                  "pdp": true,
                  "total": 2,
                  "done": 0,
                  "designs": [
                    {
                      "index": 0,
                      "name": "Recent median",
                      "inputs": {
                        "fluid_bbl_per_ft": null,
                        "proppant_lb_per_ft": null
                      },
                      "fluid_bbl_per_ft": 55.2,
                      "proppant_lb_per_ft": 2716,
                      "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                      "formations": [
                        {
                          "formation": "WOLFCAMP A",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 54.5,
                          "proppant_lb_per_ft": 2709.5,
                          "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                        }
                      ]
                    },
                    {
                      "index": 1,
                      "name": "Upsized",
                      "inputs": {
                        "fluid_bbl_per_ft": 60,
                        "proppant_lb_per_ft": 3000
                      },
                      "fluid_bbl_per_ft": 60,
                      "proppant_lb_per_ft": 3000,
                      "completions_source": "input",
                      "formations": [
                        {
                          "formation": "WOLFCAMP A",
                          "inputs": {
                            "fluid_bbl_per_ft": 60,
                            "proppant_lb_per_ft": 3000
                          },
                          "fluid_bbl_per_ft": 60,
                          "proppant_lb_per_ft": 3000,
                          "completions_source": "input"
                        }
                      ]
                    }
                  ],
                  "decline": {
                    "eur_years": 50,
                    "terminal_decline": 0.06,
                    "b_min": 0.5,
                    "b_max": 2.5
                  },
                  "progress": 0,
                  "steps": {
                    "spacing": 1,
                    "calc": 0,
                    "forecast": 0,
                    "eur": 0
                  },
                  "created_at": "2026-10-17T21:59:49.718Z",
                  "seconds": 0,
                  "error": null,
                  "totals": null,
                  "links": {
                    "self": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                    "wells": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630?include=wells",
                    "export": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630/export"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The Idempotency-Key was already used with a different body; or, with Redis, the first request with this Idempotency-Key is still being made (after a 30 s wait); retry shortly with the same key; or `from_plan` names a plan still running, or failed.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotency": {
                    "summary": "The Idempotency-Key was used with another body",
                    "value": {
                      "error": {
                        "code": "conflict",
                        "message": "This Idempotency-Key was already used with a different request body; send a new key for a new request, or the same body for the first request's result",
                        "details": {
                          "field": "Idempotency-Key"
                        }
                      },
                      "request_id": "1d6f3a8c-5e2b-4c97-8a0d-7b4e9f2c6a13"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "The request body is over 64 MB.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "The caller already has plans queued or running, and this one would take their unfinished forecasts past GET /dataset `limits.plan_unfinished_forecasts`; `details` has `limit`, `unfinished`, `plans` and, when the body was read, `requested`. Wait for one to finish or delete one.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "conflict",
                    "message": "You already have 4 plans queued or running, with 32,000 forecasts (wells × designs). This plan would take you past 40,000, the most one caller may have unfinished at once. Wait for one to finish, or delete one (DELETE /api/v1/plans/{id}), then send it again.",
                    "details": {
                      "limit": 40000,
                      "unfinished": 32000,
                      "plans": 4,
                      "requested": 10000
                    }
                  },
                  "request_id": "5a2e7c91-3f6b-4d08-9c1e-8b4f2a6d0e37"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "description": "A model worker or the subsurface grids aren't ready, or, with Redis, the Redis that keeps Idempotency-Key records isn't answering; retry shortly with the same key.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unavailable",
                    "message": "The spacing model worker isn't running; retry shortly, and ask your Novi admin if it persists",
                    "details": {
                      "worker": "spacing"
                    }
                  },
                  "request_id": "0b5e8f2a-7c1d-4e6b-a3f9-5d2c8e4b1a70"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listPlans",
        "tags": [
          "Plans"
        ],
        "summary": "List recent plans",
        "description": "Lists the request tenant's plans in one model set (`model_set`, else the set GET /model-sets names `default`), newest first, without their wells. With a state store, the list holds stored plans across restarts.\n\n**Legacy Forecasts.** With `origin`, the list also holds the tenant's Legacy Forecasts, as plans whose `origin.engine` is `fe`, each read only. A Legacy Forecast is a done predrill run of Novi's earlier Forecast Engine, with its wells, forecasts, EUR and, where the run has them, P10 and P90 bands. GET /plans/{id}, its wells and curves, GET /export-formats?plan= and POST /exports read one, with v2's own Arps fits on the run's curves; any other operation naming one is a 409 with `details.reason` `fe_plan_unsupported`, and a change (PATCH, DELETE, a share, economics, `from_plan`) one with `plan_read_only`.\n\nA Legacy Forecast's exports skip ARIES and the tables the run has no data for, with the presets that need them (GET /export-formats says why). A run that forecast only some streams carries only those, and an export defaults `streams` to them (another is a 400); condensate sits in the oil stream, with `stream_labels` `{\"oil\": \"condensate\"}`. A run whose results file can't be read is a failed plan (`error.code` `unavailable`, no `links.export`) that the server reads again later, and when the file changes.\n\nA Legacy Forecast belongs to no model set, so every set's list holds it: when listing several sets, send `origin=v2` after the first. Its `created_at` is when its results file was written, and `origin.ran_at` when the run was submitted. `saved` and `created_by` leave Legacy Forecasts out; `kept=true` keeps them.\n\n**Runs not yet read.** The server reads each run once, in the background, one at a time per task, and gives that time as `origin.indexed_at`. Until then the run is left out and counted in a `fe_runs_pending` warning; `created_from` says how a sync catches it later.\n\n- With `created_from`, a run whose read failed is counted in `fe_runs_pending` until its read has failed four times in a row; it then lists as a failed plan (`status` `error`).\n- Without `created_from`, paging by `next_cursor` holds every run only if no page carried `fe_runs_pending`; otherwise list again from the first page.\n- When the runs can't be listed, `origin=all` answers the v2 plans with a `fe_runs_unavailable` warning, and `origin=fe` a 503.\n\n**Syncing.** A sync lists each model set with `origin=all&kept=true&status=done&updated_from=<last sync start minus 15 minutes>&include=storage&model_set=<id>`, paging by `next_cursor`. GET /conventions, section `sync`, has the steps.\n\n**Errors.** An invalid parameter value is a 400; a tenant the server doesn't serve is a 404.",
        "parameters": [
          {
            "name": "origin",
            "in": "query",
            "description": "`all`: v2 plans and Legacy Forecasts, newest first on one cursor; `fe`: Legacy Forecasts only; `v2`: v2 plans only. Any of them adds `origin`, `streams` and, where a stream's label isn't its name, `stream_labels` to every plan, and `warnings` and `warning_details` to the answer. Absent: v2 plans only, without those fields. Any other value is a 400.",
            "schema": {
              "type": "string",
              "enum": [
                "fe",
                "v2",
                "all"
              ]
            }
          },
          {
            "name": "created_from",
            "in": "query",
            "description": "Only plans created at or after this date-time, such as `2026-11-12T00:00:00Z`, with or without `origin`. It finds plans created since, not plans finished since: re-read the running plans a previous call saw.\n\nWith `origin`, a Legacy Forecast is kept when its `created_at` or its `origin.indexed_at` is at or after this time, so each run read since your last sync is in your next one and a sync never lists again from the first page. The server lists the runs afresh first; a run not yet read is counted in a `fe_runs_pending` warning and comes in the first later answer whose `created_from` is at or before the time it is read. A run's `created_at` is its results file's LastModified, which can come before the run is listable: send `created_from` a margin before your last sync, such as 15 minutes, and dedupe the plans by id.\n\nTakes a date, `YYYY-MM-DD`, read as 00:00 UTC, or a date-time, `YYYY-MM-DDTHH:MM[:SS]` with optional fractional seconds (up to 9 digits, cut to the millisecond) and `Z` or a `+HH:MM` or `-HH:MM` offset. A day or time that doesn't exist, or any other form, is a 400.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "updated_from",
            "in": "query",
            "description": "Only plans changed at or after this date-time, such as `2026-11-12T00:00:00Z`: a v2 plan whose `created_at` or last stored change is at or after it. With `created_from` it is a 400.\n\nA plan's stored change time moves while it runs, when it finishes, and when it is renamed, saved, unsaved or shared, so a plan saved after your last sync is in your next one. Send `status=done` to leave running plans out. Without a state store it reads `created_at` alone. A sync keeps the v2 plan ids it hasn't seen.\n\nWith `origin`, a Legacy Forecast is listed as `created_from` lists it. It keeps its id when its numbers change: read it again when its `origin.indexed_at` is newer than your copy.\n\nTakes a date, `YYYY-MM-DD`, read as 00:00 UTC, or a date-time, `YYYY-MM-DDTHH:MM[:SS]` with optional fractional seconds (up to 9 digits, cut to the millisecond) and `Z` or a `+HH:MM` or `-HH:MM` offset. A day or time that doesn't exist, or any other form, is a 400.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "include",
            "in": "query",
            "description": "`storage` adds Plan.storage, each plan's retention and active share count (null without a state store, and on a Legacy Forecast). `counts` adds `counts`. Unknown or duplicate names are 400.",
            "schema": {
              "type": "string",
              "enum": [
                "storage",
                "counts",
                "storage,counts",
                "counts,storage"
              ]
            }
          },
          {
            "name": "saved",
            "in": "query",
            "description": "Only saved or unsaved plans; `true` is empty without a state store. Any other nonempty value is 400.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "kept",
            "in": "query",
            "description": "`true`: saved plans and every Legacy Forecast; `false`: unsaved plans only. Unlike `saved`, it keeps Legacy Forecasts, which join only with `origin` `fe` or `all`; without `origin` the list holds v2 plans only. With `saved`, or any other nonempty value, it is a 400.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "created_by",
            "in": "query",
            "description": "`me`, or person keys from `facets.created_by`, comma-separated: only the plans those people posted. `me` works with a state store or without.\n\nA person key is `u_` and 16 hex digits: it names a teammate without putting an email in the URL, and stays the same for that email in this tenant. Your own key reads as `me`. Older plans and Legacy Forecasts name no one and match nothing. A well-formed key that no plan names matches nothing; any other value, or one named twice, is a 400: an email never goes in a URL.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Only plans whose name contains this text, ignoring case. On a Legacy Forecast its run name (`origin.run`) counts too. Spaces at either end are dropped, and an empty `q` is as if absent. Over 200 characters is a 400. With or without `origin`.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "shared",
            "in": "query",
            "description": "`true`: only plans with an active share link; `false`: only plans with none. Like `saved`, it leaves Legacy Forecasts out; without a state store `true` is empty. Any other nonempty value is a 400.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Only plans with one of these statuses, comma-separated: `done`, `running` (which includes queued plans), `error`. Legacy Forecasts are `done` or `error`. Another value, or one named twice, is a 400.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "streams",
            "in": "query",
            "description": "Only plans whose forecast streams are one of these sets, comma-separated, such as `oil-gas,gas`. It needs `origin` (a 400 without it), as plans carry `streams` only with it.\n\nA set names its streams in oil, gas, water order, joined by `-`, with a stream's label in its place where it has one: `oil-gas`, `gas`, `condensate-gas`, `oil-gas-water`. `facets.streams` lists the sets present, each with its name. A well-formed set that no plan has matches nothing; any other value, or one named twice, is a 400.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ran_from",
            "in": "query",
            "description": "Only plans that ran at or after `ran_from` and at or before `ran_to`: a Legacy Forecast's `origin.ran_at` (else its `created_at`) and a v2 plan's `created_at`.\n\nUnlike `created_from`, which a sync client uses, neither ever matches on when a run was indexed. A value that isn't a date-time, or `ran_from` after `ran_to`, is a 400.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "ran_to",
            "in": "query",
            "description": "Only plans that ran at or after `ran_from` and at or before `ran_to`: a Legacy Forecast's `origin.ran_at` (else its `created_at`) and a v2 plan's `created_at`.\n\nUnlike `created_from`, which a sync client uses, neither ever matches on when a run was indexed. A value that isn't a date-time, or `ran_from` after `ran_to`, is a 400.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "ran_within",
            "in": "query",
            "description": "Only plans that ran within this long before the server's clock: an ISO 8601 duration of whole days, `P1D` to `P3660D`, or whole months, `P1M` to `P120M`, such as `P30D` or `P3M`.\n\nA month back is the same day and time of the earlier month, or its last day when it has fewer. It matches the time `ran_from` matches and moves with each call, so a saved filter stays relative. With `ran_from` or `ran_to`, or in another form, it is a 400.",
            "schema": {
              "type": "string",
              "pattern": "^P([1-9][0-9]{0,3}D|[1-9][0-9]{0,2}M)$"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "The order: `ran_at`, `name`, `total`, `status` or `created_by`, with `-` first for descending, as `-ran_at`. Absent: newest first by `created_at`.\n\n- `ran_at`: when it ran, as `ran_from` reads it.\n- `name`: ignoring case; unnamed last.\n- `total`: its wells.\n- `status`: `done`, `running`, then `error`.\n- `created_by`: your own plans first, then by the poster's email ignoring case; Legacy Forecasts and plans that name no one last.\n\nDescending keeps the plans without a value last; `status` and `created_by` keep each group newest first; every sort breaks its last tie on `id`, in its direction. A cursor holds its sort: send the same `sort` with it. Between pages, a `name` or `status` sort can skip or repeat a plan renamed or finished, and a `created_by` sort's cursor is a 400 once no listed plan is that poster's: list again from the first page. Another value is a 400.",
            "schema": {
              "type": "string",
              "enum": [
                "ran_at",
                "-ran_at",
                "name",
                "-name",
                "total",
                "-total",
                "status",
                "-status",
                "created_by",
                "-created_by"
              ]
            }
          },
          {
            "name": "facets",
            "in": "query",
            "description": "Adds `facets`: for each field named, comma-separated, of `origin`, `status`, `saved`, `shared`, `created_by`, `streams` and `month`, the values with the number of plans that pass every other filter but that field's own, as a faceted search counts; `month` is counted without `ran_from`, `ran_to` and `ran_within`. Needs `origin`. Another name, or one named twice, is a 400.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Page to read: `next_cursor` from the previous page, opaque. A page starts strictly after the last plan of the page before, so creating or deleting plans between pages neither skips nor repeats a plan.\n\nA cursor holds its sort and no filter: send the same `sort`, `q`, `saved`, `shared`, `status`, `created_by`, `streams`, `ran_from`, `ran_to`, `ran_within`, `kept` and `updated_from` with it. A cursor sent with another `sort`, or any other nonempty value, is a 400. A cursor an older server gave still reads from its position.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "Plans.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanList"
                },
                "example": {
                  "plans": [
                    {
                      "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                      "name": "Section 36 infill",
                      "status": "done",
                      "pdp": true,
                      "total": 2,
                      "done": 2,
                      "designs": [
                        {
                          "index": 0,
                          "name": "Recent median",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 55.2,
                          "proppant_lb_per_ft": 2716,
                          "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": null,
                                "proppant_lb_per_ft": null
                              },
                              "fluid_bbl_per_ft": 54.5,
                              "proppant_lb_per_ft": 2709.5,
                              "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                            }
                          ]
                        },
                        {
                          "index": 1,
                          "name": "Upsized",
                          "inputs": {
                            "fluid_bbl_per_ft": 60,
                            "proppant_lb_per_ft": 3000
                          },
                          "fluid_bbl_per_ft": 60,
                          "proppant_lb_per_ft": 3000,
                          "completions_source": "input",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": 60,
                                "proppant_lb_per_ft": 3000
                              },
                              "fluid_bbl_per_ft": 60,
                              "proppant_lb_per_ft": 3000,
                              "completions_source": "input"
                            }
                          ]
                        }
                      ],
                      "decline": {
                        "eur_years": 50,
                        "terminal_decline": 0.06,
                        "b_min": 0.5,
                        "b_max": 2.5
                      },
                      "progress": 1,
                      "created_at": "2026-10-17T21:59:49.718Z",
                      "seconds": 0.08,
                      "error": null,
                      "totals": [
                        {
                          "design": 0,
                          "wells_with_forecast": 2,
                          "wells_flagged": 0,
                          "forecast": {
                            "oil": {
                              "model_num": "M20260930-sample-O-d1",
                              "target": "novi_oil",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                398361.2,
                                592769.9,
                                723038.3
                              ],
                              "missing": []
                            },
                            "gas": {
                              "model_num": "M20260930-sample-G-d1",
                              "target": "novi_gas",
                              "unit": "mcf",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                752385.2,
                                1255796.5,
                                1652522.2
                              ],
                              "missing": []
                            },
                            "water": {
                              "model_num": "M20260930-sample-W-d1",
                              "target": "novi_water",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                799833.1,
                                1143571.4,
                                1382059
                              ],
                              "missing": []
                            }
                          },
                          "eur": {
                            "oil": {
                              "value": 1712047.8,
                              "days": 18240,
                              "wells": 2
                            },
                            "gas": {
                              "value": 6364416.5,
                              "days": 18240,
                              "wells": 2
                            },
                            "boe": {
                              "value": 2772783.9,
                              "wells": 2
                            }
                          }
                        },
                        {
                          "design": 1,
                          "wells_with_forecast": 2,
                          "wells_flagged": 0,
                          "forecast": {
                            "oil": {
                              "model_num": "M20260930-sample-O-d1",
                              "target": "novi_oil",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                416334,
                                619513.8,
                                755659.5
                              ],
                              "missing": []
                            },
                            "gas": {
                              "model_num": "M20260930-sample-G-d1",
                              "target": "novi_gas",
                              "unit": "mcf",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                786330.4,
                                1312454.1,
                                1727078.8
                              ],
                              "missing": []
                            },
                            "water": {
                              "model_num": "M20260930-sample-W-d1",
                              "target": "novi_water",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                843073.9,
                                1202322.8,
                                1451570.2
                              ],
                              "missing": []
                            }
                          },
                          "eur": {
                            "oil": {
                              "value": 1789297.5,
                              "days": 18240,
                              "wells": 2
                            },
                            "gas": {
                              "value": 6651556.6,
                              "days": 18240,
                              "wells": 2
                            },
                            "boe": {
                              "value": 2897890.3,
                              "wells": 2
                            }
                          }
                        }
                      ],
                      "links": {
                        "self": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                        "wells": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630?include=wells",
                        "export": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630/export"
                      }
                    }
                  ],
                  "next_cursor": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "delete": {
        "operationId": "deletePlans",
        "tags": [
          "Plans"
        ],
        "summary": "Delete unfinished plans",
        "description": "Deletes the queued and running plans that match in the request's tenant and model set, newest first, each as DELETE /plans/{id}?unless=saved does: a running plan stops after its chunks in flight, and a saved or shared plan stays, counted in `kept`.\n\n**Filters.** `status=running` is required (a queued plan reads `running`), with at least one of `created_by`, `created_from` and `created_to`; each one sent narrows the match. A done or failed plan is never touched. Any other parameter is a 400, so a misspelt filter can't widen the delete.\n\n**Limits.** One call deletes at most 200 plans; `remaining` counts the matches left, so call again until it is 0.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": true,
            "description": "`running`: the queued and running plans. Missing or any other value is a 400.",
            "schema": {
              "type": "string",
              "enum": [
                "running"
              ]
            }
          },
          {
            "name": "created_by",
            "in": "query",
            "description": "`me`: only the plans the request's user posted, matched on the stored email; older plans name no one and don't match. Reach another user's plans by `created_from` and `created_to`. Any other value is a 400: an email never goes in a URL.",
            "schema": {
              "type": "string",
              "enum": [
                "me"
              ]
            }
          },
          {
            "name": "created_from",
            "in": "query",
            "description": "Only plans created at or after this date-time, such as `2026-11-12T00:00:00Z`. One after `created_to` is a 400.\n\nTakes a date, `YYYY-MM-DD`, read as 00:00 UTC, or a date-time, `YYYY-MM-DDTHH:MM[:SS]` with optional fractional seconds (up to 9 digits, cut to the millisecond) and `Z` or a `+HH:MM` or `-HH:MM` offset. A day or time that doesn't exist, or any other form, is a 400.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "created_to",
            "in": "query",
            "description": "Only plans created at or before this date-time, such as `2026-11-12T06:00:00Z`.\n\nTakes a date, `YYYY-MM-DD`, read as 00:00 UTC, or a date-time, `YYYY-MM-DDTHH:MM[:SS]` with optional fractional seconds (up to 9 digits, cut to the millisecond) and `Z` or a `+HH:MM` or `-HH:MM` offset. A day or time that doesn't exist, or any other form, is a 400.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "What was deleted, kept and left.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedPlans"
                },
                "example": {
                  "deleted": 2,
                  "kept": 1,
                  "remaining": 0,
                  "ids": [
                    "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                    "3f1d2c4b-5a69-4e7f-8b0c-1d2e3f4a5b6c"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "parameters": []
    },
    "/plans/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        }
      ],
      "get": {
        "operationId": "getPlan",
        "tags": [
          "Plans"
        ],
        "summary": "Get a plan",
        "description": "A plan's status, progress and designs and, once it is done, its totals per design (each stream summed over the wells with a forecast). `include=wells` adds its wells.\n\n**Wells.** `include=wells` adds each well's inputs, TVD, forecasts per design and spacing summary, in plan order, all of them unless you page with `limit` and `cursor`. `sort` ranks them (`include=wells&sort=eur_boe&limit=10` is the top ten by BOE EUR); `fields`, `wells`, `scenario`, `formation`, `pad`, `q`, `designs` and `ip_days` cut them down, each as its parameter says. A failed plan returns no wells.\n\n**While it runs.** The answer carries `Retry-After: 1` and no `ETag`; send `wait` instead of polling. `include=wells` returns the wells finished so far, in finish order, and its `next_cursor` keeps paging in that order after the plan is done, so a poll fetches only new wells and gets every well once. `sort` answers 409 meanwhile; GET /plans/{id}/stats answers partial figures.\n\nA plan running on another server lists no wells until it is done, and `next_cursor` stays where yours was. Its checks that need its wells or designs (a `scenario` or `pad` it lacks, a `designs` or `design` index past its designs, every `eur_curve` check but its value) answer once it is done; the rest answer at once.\n\n**Caching.** A done or failed plan's answer carries an `ETag`; send it as `If-None-Match` for a 304.\n\n**Legacy Forecasts.** GET /plans?origin=all lists the tenant's Legacy Forecasts beside its plans, each read only. A Legacy Forecast is a done predrill run of Novi's earlier Forecast Engine, with its wells, forecasts, EUR and, where the run has them, P10 and P90 bands. GET /plans/{id}, its wells and curves, GET /export-formats?plan= and POST /exports read one, with v2's own Arps fits on the run's curves; any other operation naming one is a 409 with `details.reason` `fe_plan_unsupported`, and a change (PATCH, DELETE, a share, economics, `from_plan`) one with `plan_read_only`.\n\nA Legacy Forecast's exports skip ARIES and the tables the run has no data for, with the presets that need them (GET /export-formats says why). A run that forecast only some streams carries only those, and an export defaults `streams` to them (another is a 400); condensate sits in the oil stream, with `stream_labels` `{\"oil\": \"condensate\"}`. A run whose results file can't be read is a failed plan (`error.code` `unavailable`, no `links.export`) that the server reads again later, and when the file changes. A Legacy Forecast always carries `origin`, `streams` and `stream_labels`; its one design is `As run`, its wells carry their own completions, and `include=storage` answers `storage: null`.\n\n**Retention.** With a state store, an unsaved plan is kept for the server's scratch period after it is made (90 days unless the server sets another; `storage.expires_at` says when) and deleted within a minute of `expires_at`; a saved plan is kept until deleted. Saving clears `expires_at`; unsaving starts a new scratch period. A deleted plan is gone from the API at once, its shares revoked and its attached documents deleted.",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "description": "What to add, of `wells`, `storage`, `decline_base`, `request`, `origin` and `timings`. A 400 for an unknown name lists the six in `details.allowed`.\n\n- `wells`: per-well summaries. The wells-only parameters need it.\n- `storage`: retention, tenant and active share count; null without a state store.\n- `decline_base`: `inputs.resolved.decline.base` on each well that has `resolved.decline`, and nothing on a plan with no layer below it; older plans leave it out. Needs `wells` (400 without it), and with `fields` needs `inputs` kept (400 otherwise).\n- `request`: the body POST /plans accepted, keys as sent after an assumption set's fill, without `callback_url` and `dry_run`, so a client can show a plan's inputs and send them back. A field sent as null comes back null unless the set filled it.\n  - A plan made with `from_plan` answers its source's body. Older plans, and plans made through the legacy POST /api/plan or re-run from one, answer null. Without a state store it is a 409.\n- `origin`: `origin`, `streams` and `stream_labels`.\n- `timings`: where the plan's time went per worker step; alone, it reads no more of the plan than a GET without `include`.\n\nWhen any but `wells` is named, names may be comma-separated or repeated, each once, and unknown or duplicate names are a 400. Otherwise only the first `include` value is read, and it must be exactly `wells` or empty (spaces and unknown values are a 400). The schema lists every set of names this operation takes; the same names in another order are taken too.",
            "schema": {
              "type": "string",
              "enum": [
                "wells",
                "storage",
                "wells,storage",
                "storage,wells",
                "wells,decline_base",
                "decline_base,wells",
                "wells,storage,decline_base",
                "request",
                "wells,request",
                "request,wells",
                "storage,request",
                "wells,storage,request",
                "origin",
                "wells,origin",
                "storage,origin",
                "wells,storage,origin",
                "timings",
                "wells,timings",
                "storage,timings",
                "wells,storage,timings",
                "request,origin",
                "request,timings",
                "origin,timings",
                "wells,decline_base,request",
                "wells,decline_base,origin",
                "wells,decline_base,timings",
                "wells,request,origin",
                "wells,request,timings",
                "wells,origin,timings",
                "storage,request,origin",
                "storage,request,timings",
                "storage,origin,timings",
                "request,origin,timings",
                "wells,storage,decline_base,request",
                "wells,storage,decline_base,origin",
                "wells,storage,decline_base,timings",
                "wells,storage,request,origin",
                "wells,storage,request,timings",
                "wells,storage,origin,timings",
                "wells,decline_base,request,origin",
                "wells,decline_base,request,timings",
                "wells,decline_base,origin,timings",
                "wells,request,origin,timings",
                "storage,request,origin,timings",
                "wells,storage,decline_base,request,origin",
                "wells,storage,decline_base,request,timings",
                "wells,storage,decline_base,origin,timings",
                "wells,storage,request,origin,timings",
                "wells,decline_base,request,origin,timings",
                "wells,storage,decline_base,request,origin,timings"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "With include=wells: wells per page, at most 10,000 also on a server that allows bigger plans; page the rest with `cursor`.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000,
              "default": 10000
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Page to read: `next_cursor` from the previous page. One from a running plan keeps paging in finish order after the plan is done, so a client polling with it gets every well once, and it can't be sent with `sort` (400 once the plan is done or with `wait`; a running plan answers 409 to `sort` first).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "With include=wells (400 without): order the wells by this metric under `design`, wells without a value last in either order and ties in plan order; `limit` and `cursor` page the sorted order.\n\nPer-well metrics: `eur_oil` (bbl), `eur_gas` (mcf) and `eur_boe` (BOE) are each well's EUR and need a plan made with `eur: true` (400 otherwise); `cum_oil`, `cum_gas` and `cum_boe` are the forecast's cumulative volume at `ip_day`. BOE is oil + gas / 6, only for wells with both.",
            "schema": {
              "type": "string",
              "enum": [
                "eur_boe",
                "eur_oil",
                "eur_gas",
                "cum_boe",
                "cum_oil",
                "cum_gas"
              ]
            }
          },
          {
            "name": "order",
            "in": "query",
            "description": "With sort (ignored without it): desc, largest first, or asc.",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          {
            "name": "design",
            "in": "query",
            "description": "With sort: the design whose forecasts are measured, as its index in the plan's `designs`; 400 past the last one. Also selects the design whose checks fields=checks returns, and is read and range-checked then too, even without sort.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9,
              "default": 0
            }
          },
          {
            "name": "ip_day",
            "in": "query",
            "description": "With sort (ignored without it): for a cum_ metric, the ip_day (days since first production) whose cumulative volume is measured: one of GET /dataset `ip_days`, default 1080 (3 years). 400 with an eur_ metric.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1080
            }
          },
          {
            "name": "wait",
            "in": "query",
            "description": "Use this instead of polling: on a running plan, the answer is held until its status changes to done or error, or this many seconds pass.\n\nWhole seconds, 1 to 25 (400 otherwise). The answer is what a GET without `wait` would get when the wait ends, `Retry-After` included; a finished job answers at once. A client that disconnects ends the wait. With include=wells it waits on the status only, not on newly finished wells, and the page is read when the answer goes out; with sort on a plan still running when the wait ends, it answers 409 as without wait.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25
            }
          },
          {
            "name": "fields",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Only these fields, comma-separated; absent or empty, every field. `index` is always kept, and the response keeps its own key order.\n\nAllowed: with include=wells (400 without it), any of each well's fields listed below, and `value` with `sort`.\n\nFor example `label,forecasts`. A well that could not be placed also always keeps `error`. The plan's own fields, `totals` and `next_cursor` are always there.\n\nThe fields: `index`, `key`, `label`, `inputs`, `lateral_length_ft`, `estimates`, `forecasts`, `spacing`, `checks`, `name`, `nearest_same_formation_ft`, `lateral_length_source`.\n\n- `value`: the sort metric's value of each well, under `design`, `ip_day` and `normalize_lateral_ft`, rounded to 0.1 in the metric's unit (as GET /plans/{id}/stats); null for a well without one. 400 without `sort`. A ranking page of `fields=label,value` is about a tenth of one with `forecasts`.\n- `checks`: each well's checks for `design` (default 0), the same object as that design's `forecasts[].checks`, or null when that design has none (a failed well, or no checks). Readable without `sort`. Show the flag beside any number you quote from a well whose `checks.flagged` is true.\n- `nearest_same_formation_ft`: as the PlanWellSummary schema describes it. Readable without `sort`.\n\nNames are top-level only (no dots), case-sensitive and never empty; one not allowed here is a 400 with the allowed names in `details.allowed`."
          },
          {
            "name": "wells",
            "in": "query",
            "description": "With include=wells (400 without it), only these wells: their plan indexes (each row's `index`, from 0), comma-separated, at most 500 different ones; a repeat counts once.\n\nUse it to read a few wells of a big plan in one call, as `wells=3,1999&fields=lateral_length_ft,forecasts`. The rows come in plan order, in `sort` order, or after a running plan's cursor in finish order, and `fields`, `limit` and `cursor` work on these wells only; while the plan runs, those of them finished so far. An index the plan doesn't have, or anything but whole numbers and commas, is a 400.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scenario",
            "in": "query",
            "description": "With include=wells (400 without it), only one scenario's wells, named exactly as the plan's `scenarios` list it, URL-encoded: `660 ft` is `scenario=660%20ft`.\n\nAn empty name, or one the plan doesn't have, is a 400 whose `details.scenarios` lists the plan's scenarios (empty on a plan without them, where any name is a 400). A name over 60 characters is a 400 without the list.\n\n`scenario`, `formation`, `q`, `pad` and `wells` apply together, and `sort`, `fields`, `limit` and `cursor` work on the wells that pass. `matched` counts those wells, finished or not, while `total` stays the whole plan; while the plan runs, the rows are those finished so far. A cursor holds no filter: send the same filters with it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            }
          },
          {
            "name": "formation",
            "in": "query",
            "description": "With include=wells (400 without it), only the wells landing in these formations: one name or a comma-separated list, case-insensitive, as GET /wells takes it. Empty is no filter.\n\nA name GET /formations doesn't list is a 400 with them in `details.allowed`; a listed one none of the plan's wells land in gives an empty page. A well with no formation matches none.\n\n`scenario`, `formation`, `q`, `pad` and `wells` apply together, and `sort`, `fields`, `limit` and `cursor` work on the wells that pass. `matched` counts those wells, finished or not, while `total` stays the whole plan; while the plan runs, the rows are those finished so far. A cursor holds no filter: send the same filters with it.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pad",
            "in": "query",
            "description": "With include=wells (400 without it), only the wells on this pad: one key, not a list, trimmed; a well sent with `\"pad\": 1` or `\"pad\": \"1\"` matches `pad=1`.\n\nEmpty, or over 60 characters, is a 400, and so is any key on a plan whose wells name no pads. A key no well has is a 400 whose `details.pads` lists the plan's first 50 keys in plan order.\n\n`scenario`, `formation`, `q`, `pad` and `wells` apply together, and `sort`, `fields`, `limit` and `cursor` work on the wells that pass. `matched` counts those wells, finished or not, while `total` stays the whole plan; while the plan runs, the rows are those finished so far. A cursor holds no filter: send the same filters with it.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "With include=wells (400 without it), only the wells whose label, or name when they have one, contains this text, ignoring case: `well 12` matches Plan well 12. Empty is no filter.\n\nNo wildcards. Spaces at either end are ignored. Up to 100 characters (400 past it).\n\n`scenario`, `formation`, `q`, `pad` and `wells` apply together, and `sort`, `fields`, `limit` and `cursor` work on the wells that pass. `matched` counts those wells, finished or not, while `total` stays the whole plan; while the plan runs, the rows are those finished so far. A cursor holds no filter: send the same filters with it.",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "eur_curve",
            "in": "query",
            "description": "With include=wells, on a plan made with `eur: true`: adds each well's oil and gas EUR curve (and water's with `eur_water`) as `eur.curve`, to compare a few plan wells to EUR.\n\nOnly on a page of at most 25 wells with `month` and 100 with `year` (a `limit` that small, or `wells` with at most that many indexes) whose `fields`, if sent, keep `forecasts`; 400 otherwise, with `details.max`.\n\nThe curve: cumulative volumes to the EUR's `days`.\n\nIt continues the forecast from its last ip_day on the same decline fit: `month` every 30 days (the export's monthly cumulatives), `year` every 360 days plus the EUR's day. A decline-curve extension, not a model output.",
            "schema": {
              "type": "string",
              "enum": [
                "month",
                "year"
              ]
            }
          },
          {
            "name": "designs",
            "in": "query",
            "description": "With include=wells (400 without it), each well's `forecasts` keep only these designs: their indexes in the plan's `designs`, comma-separated, each once and in range. Absent: every design.\n\nA repeat or an index out of range is a 400; past the last, `details.designs` is the plan's count. Kept forecasts come in the plan's design order, each with its own `design` index. With `eur_curve`, only the kept designs get curves.\n\n`designs` trims only what each well carries: `design` is the one design `sort` ranks by and `value` measures, and `designs` changes neither it, the order, `value`, `next_cursor` nor the plan's own fields.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ip_days",
            "in": "query",
            "description": "With include=wells (400 without it), each kept forecast's streams hold only these ip_days, comma-separated: their values and P10/P90 bands. Absent: every ip_day.\n\nThey are cut and checked as POST /forecasts `ip_days` cuts a forecast: up to 36 different ones of GET /dataset `ip_days`, else a 400 with them in `details.allowed`, and they come back ascending and once each. EURs are fit on the whole curve and don't change; with `eur_curve`, each curve still starts after the forecast's last ip_day before the cut. `sort`, `ip_day` and `value` don't change.\n\nA cut that starts after 30 or skips an ip_day can't be sent to POST /economics as `curves` (a 400): price the plan by reference, which uses every ip_day.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "boe",
            "in": "query",
            "description": "`true` adds `boe` beside `oil`, `gas` and `water` in every forecast that has streams, computed when read, so older plans have it too. Absent, empty or `false`: no `boe` key anywhere.\n\nBOE is oil plus gas / 6 (6 mcf per bbl), on ip_days where both have a value; on a set serving one of them the other counts 0, and serving neither, BOE is 0.\n\nIts P10 adds oil's P10 and gas's P10 / 6 (P90 likewise). The models predict each stream apart, so this isn't the P10 of BOE itself; it is as wide as BOE's would be if oil and gas moved together. Novi's P10 is the low case. Totals add the BOE of the wells that have both oil and gas forecasts, and say how many in `wells`. On `totals`, and with include=wells on each well's forecasts; with band_eur, `totals[].eur.boe` adds `p10` and `p90`. Anything else is a 400.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "normalize_lateral_ft",
            "in": "query",
            "description": "With sort (ignored without it, as design and ip_day are): scale each well's metric to this lateral length before sorting, × normalize_lateral_ft / its lateral_length_ft, so 1000 ranks wells per 1,000 ft of lateral; `value` is then the scaled one. 100 to 20,000.",
            "schema": {
              "type": "number",
              "minimum": 100,
              "maximum": 20000
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The plan.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Plan"
                },
                "examples": {
                  "running": {
                    "summary": "Running",
                    "value": {
                      "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                      "name": "Section 36 infill",
                      "status": "running",
                      "pdp": true,
                      "total": 2,
                      "done": 0,
                      "designs": [
                        {
                          "index": 0,
                          "name": "Recent median",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 55.2,
                          "proppant_lb_per_ft": 2716,
                          "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": null,
                                "proppant_lb_per_ft": null
                              },
                              "fluid_bbl_per_ft": 54.5,
                              "proppant_lb_per_ft": 2709.5,
                              "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                            }
                          ]
                        },
                        {
                          "index": 1,
                          "name": "Upsized",
                          "inputs": {
                            "fluid_bbl_per_ft": 60,
                            "proppant_lb_per_ft": 3000
                          },
                          "fluid_bbl_per_ft": 60,
                          "proppant_lb_per_ft": 3000,
                          "completions_source": "input",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": 60,
                                "proppant_lb_per_ft": 3000
                              },
                              "fluid_bbl_per_ft": 60,
                              "proppant_lb_per_ft": 3000,
                              "completions_source": "input"
                            }
                          ]
                        }
                      ],
                      "decline": {
                        "eur_years": 50,
                        "terminal_decline": 0.06,
                        "b_min": 0.5,
                        "b_max": 2.5
                      },
                      "progress": 0,
                      "steps": {
                        "spacing": 1,
                        "calc": 0,
                        "forecast": 0,
                        "eur": 0
                      },
                      "created_at": "2026-10-17T21:59:49.718Z",
                      "seconds": 0.4,
                      "error": null,
                      "totals": null,
                      "links": {
                        "self": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                        "wells": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630?include=wells",
                        "export": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630/export"
                      }
                    }
                  },
                  "done": {
                    "summary": "Done",
                    "value": {
                      "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                      "name": "Section 36 infill",
                      "status": "done",
                      "pdp": true,
                      "total": 2,
                      "done": 2,
                      "designs": [
                        {
                          "index": 0,
                          "name": "Recent median",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 55.2,
                          "proppant_lb_per_ft": 2716,
                          "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": null,
                                "proppant_lb_per_ft": null
                              },
                              "fluid_bbl_per_ft": 54.5,
                              "proppant_lb_per_ft": 2709.5,
                              "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                            }
                          ]
                        },
                        {
                          "index": 1,
                          "name": "Upsized",
                          "inputs": {
                            "fluid_bbl_per_ft": 60,
                            "proppant_lb_per_ft": 3000
                          },
                          "fluid_bbl_per_ft": 60,
                          "proppant_lb_per_ft": 3000,
                          "completions_source": "input",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": 60,
                                "proppant_lb_per_ft": 3000
                              },
                              "fluid_bbl_per_ft": 60,
                              "proppant_lb_per_ft": 3000,
                              "completions_source": "input"
                            }
                          ]
                        }
                      ],
                      "decline": {
                        "eur_years": 50,
                        "terminal_decline": 0.06,
                        "b_min": 0.5,
                        "b_max": 2.5
                      },
                      "progress": 1,
                      "created_at": "2026-10-17T21:59:49.718Z",
                      "seconds": 0.08,
                      "error": null,
                      "totals": [
                        {
                          "design": 0,
                          "wells_with_forecast": 2,
                          "wells_flagged": 0,
                          "forecast": {
                            "oil": {
                              "model_num": "M20260930-sample-O-d1",
                              "target": "novi_oil",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                398361.2,
                                592769.9,
                                723038.3
                              ],
                              "missing": []
                            },
                            "gas": {
                              "model_num": "M20260930-sample-G-d1",
                              "target": "novi_gas",
                              "unit": "mcf",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                752385.2,
                                1255796.5,
                                1652522.2
                              ],
                              "missing": []
                            },
                            "water": {
                              "model_num": "M20260930-sample-W-d1",
                              "target": "novi_water",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                799833.1,
                                1143571.4,
                                1382059
                              ],
                              "missing": []
                            }
                          },
                          "eur": {
                            "oil": {
                              "value": 1712047.8,
                              "days": 18240,
                              "wells": 2
                            },
                            "gas": {
                              "value": 6364416.5,
                              "days": 18240,
                              "wells": 2
                            },
                            "boe": {
                              "value": 2772783.9,
                              "wells": 2
                            }
                          }
                        },
                        {
                          "design": 1,
                          "wells_with_forecast": 2,
                          "wells_flagged": 0,
                          "forecast": {
                            "oil": {
                              "model_num": "M20260930-sample-O-d1",
                              "target": "novi_oil",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                416334,
                                619513.8,
                                755659.5
                              ],
                              "missing": []
                            },
                            "gas": {
                              "model_num": "M20260930-sample-G-d1",
                              "target": "novi_gas",
                              "unit": "mcf",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                786330.4,
                                1312454.1,
                                1727078.8
                              ],
                              "missing": []
                            },
                            "water": {
                              "model_num": "M20260930-sample-W-d1",
                              "target": "novi_water",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                843073.9,
                                1202322.8,
                                1451570.2
                              ],
                              "missing": []
                            }
                          },
                          "eur": {
                            "oil": {
                              "value": 1789297.5,
                              "days": 18240,
                              "wells": 2
                            },
                            "gas": {
                              "value": 6651556.6,
                              "days": 18240,
                              "wells": 2
                            },
                            "boe": {
                              "value": 2897890.3,
                              "wells": 2
                            }
                          }
                        }
                      ],
                      "links": {
                        "self": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                        "wells": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630?include=wells",
                        "export": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630/export"
                      }
                    }
                  },
                  "wells": {
                    "summary": "Done, include=wells (cut to one of its wells)",
                    "value": {
                      "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                      "name": "Section 36 infill",
                      "status": "done",
                      "pdp": true,
                      "total": 2,
                      "done": 2,
                      "designs": [
                        {
                          "index": 0,
                          "name": "Recent median",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 55.2,
                          "proppant_lb_per_ft": 2716,
                          "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": null,
                                "proppant_lb_per_ft": null
                              },
                              "fluid_bbl_per_ft": 54.5,
                              "proppant_lb_per_ft": 2709.5,
                              "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                            }
                          ]
                        },
                        {
                          "index": 1,
                          "name": "Upsized",
                          "inputs": {
                            "fluid_bbl_per_ft": 60,
                            "proppant_lb_per_ft": 3000
                          },
                          "fluid_bbl_per_ft": 60,
                          "proppant_lb_per_ft": 3000,
                          "completions_source": "input",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": 60,
                                "proppant_lb_per_ft": 3000
                              },
                              "fluid_bbl_per_ft": 60,
                              "proppant_lb_per_ft": 3000,
                              "completions_source": "input"
                            }
                          ]
                        }
                      ],
                      "decline": {
                        "eur_years": 50,
                        "terminal_decline": 0.06,
                        "b_min": 0.5,
                        "b_max": 2.5
                      },
                      "progress": 1,
                      "created_at": "2026-10-17T21:59:49.718Z",
                      "seconds": 0.08,
                      "error": null,
                      "totals": [
                        {
                          "design": 0,
                          "wells_with_forecast": 2,
                          "wells_flagged": 0,
                          "forecast": {
                            "oil": {
                              "model_num": "M20260930-sample-O-d1",
                              "target": "novi_oil",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                398361.2,
                                592769.9,
                                723038.3
                              ],
                              "missing": []
                            },
                            "gas": {
                              "model_num": "M20260930-sample-G-d1",
                              "target": "novi_gas",
                              "unit": "mcf",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                752385.2,
                                1255796.5,
                                1652522.2
                              ],
                              "missing": []
                            },
                            "water": {
                              "model_num": "M20260930-sample-W-d1",
                              "target": "novi_water",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                799833.1,
                                1143571.4,
                                1382059
                              ],
                              "missing": []
                            }
                          },
                          "eur": {
                            "oil": {
                              "value": 1712047.8,
                              "days": 18240,
                              "wells": 2
                            },
                            "gas": {
                              "value": 6364416.5,
                              "days": 18240,
                              "wells": 2
                            },
                            "boe": {
                              "value": 2772783.9,
                              "wells": 2
                            }
                          }
                        },
                        {
                          "design": 1,
                          "wells_with_forecast": 2,
                          "wells_flagged": 0,
                          "forecast": {
                            "oil": {
                              "model_num": "M20260930-sample-O-d1",
                              "target": "novi_oil",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                416334,
                                619513.8,
                                755659.5
                              ],
                              "missing": []
                            },
                            "gas": {
                              "model_num": "M20260930-sample-G-d1",
                              "target": "novi_gas",
                              "unit": "mcf",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                786330.4,
                                1312454.1,
                                1727078.8
                              ],
                              "missing": []
                            },
                            "water": {
                              "model_num": "M20260930-sample-W-d1",
                              "target": "novi_water",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                843073.9,
                                1202322.8,
                                1451570.2
                              ],
                              "missing": []
                            }
                          },
                          "eur": {
                            "oil": {
                              "value": 1789297.5,
                              "days": 18240,
                              "wells": 2
                            },
                            "gas": {
                              "value": 6651556.6,
                              "days": 18240,
                              "wells": 2
                            },
                            "boe": {
                              "value": 2897890.3,
                              "wells": 2
                            }
                          }
                        }
                      ],
                      "links": {
                        "self": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                        "wells": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630?include=wells",
                        "export": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630/export"
                      },
                      "wells": [
                        {
                          "index": 0,
                          "key": "DRAWN-0",
                          "label": "Plan well 1",
                          "inputs": {
                            "shl": [
                              -101.93,
                              31.93
                            ],
                            "bhl": [
                              -101.93,
                              31.957
                            ],
                            "formation": "WOLFCAMP A",
                            "tvd_ft": null,
                            "landing_below_top_ft": null
                          },
                          "lateral_length_ft": 9823,
                          "estimates": {
                            "tvd_ft": 9111,
                            "tvd_source": "WOLFCAMP A top 8,910 ft from the structure grid + 201 ft median landing below top (19 nearby wells)"
                          },
                          "forecasts": [
                            {
                              "design": 0,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "target": "novi_oil",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  200805.7,
                                  299072.5,
                                  364991.2
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 868670.251505,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1046.244649,
                                    "d": 0.005623,
                                    "b": 1.055556,
                                    "terminal_year": 14.849347
                                  }
                                }
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "target": "novi_gas",
                                "unit": "mcf",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  376373.3,
                                  628867.6,
                                  828069.2
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 3199411.723783,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1526.499403,
                                    "d": 0.003371,
                                    "b": 1.833333,
                                    "terminal_year": 8.372079
                                  }
                                }
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "target": "novi_water",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  402666.3,
                                  576409.3,
                                  697085.8
                                ],
                                "missing": []
                              },
                              "checks": {
                                "available": true,
                                "model_num": "M20260930-sample-O-d1",
                                "flagged": false,
                                "out_of_range": [],
                                "missing": [],
                                "unknown_formation": null
                              }
                            },
                            {
                              "design": 1,
                              "oil": {
                                "model_num": "M20260930-sample-O-d1",
                                "target": "novi_oil",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  209865.5,
                                  312565.7,
                                  381458.4
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 907863.155764,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1093.450595,
                                    "d": 0.005623,
                                    "b": 1.055556,
                                    "terminal_year": 14.849347
                                  }
                                }
                              },
                              "gas": {
                                "model_num": "M20260930-sample-G-d1",
                                "target": "novi_gas",
                                "unit": "mcf",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  393354,
                                  657240.1,
                                  865429.1
                                ],
                                "missing": [],
                                "eur": {
                                  "value": 3343766.878607,
                                  "days": 18240,
                                  "arps": {
                                    "q_i": 1595.375237,
                                    "d": 0.003371,
                                    "b": 1.833333,
                                    "terminal_year": 8.372079
                                  }
                                }
                              },
                              "water": {
                                "model_num": "M20260930-sample-W-d1",
                                "target": "novi_water",
                                "unit": "bbl",
                                "ip_days": [
                                  360,
                                  720,
                                  1080
                                ],
                                "values": [
                                  424411.6,
                                  605994.4,
                                  732115.4
                                ],
                                "missing": []
                              },
                              "checks": {
                                "available": true,
                                "model_num": "M20260930-sample-O-d1",
                                "flagged": false,
                                "out_of_range": [],
                                "missing": [],
                                "unknown_formation": null
                              }
                            }
                          ],
                          "spacing": {
                            "node": {
                              "azimuth": 0.822377,
                              "heel": [
                                -101.93,
                                31.93
                              ],
                              "heel_is_virtual": false,
                              "pad_wells": 0
                            },
                            "neighbor_count": 5
                          }
                        }
                      ],
                      "next_cursor": null
                    }
                  },
                  "scheduled": {
                    "summary": "Done, with TIL dates (by_date) and bands",
                    "value": {
                      "id": "1532d447-e989-42ac-81c0-c708d5d278a2",
                      "name": "Section 36 schedule",
                      "status": "done",
                      "pdp": true,
                      "total": 2,
                      "done": 2,
                      "designs": [
                        {
                          "index": 0,
                          "name": "Design 1",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 55.2,
                          "proppant_lb_per_ft": 2716,
                          "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": null,
                                "proppant_lb_per_ft": null
                              },
                              "fluid_bbl_per_ft": 54.5,
                              "proppant_lb_per_ft": 2709.5,
                              "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                            }
                          ]
                        }
                      ],
                      "bands": {
                        "percentiles": [
                          10,
                          90
                        ],
                        "method": "Novi's predrill bands (split conformal)",
                        "eur": false
                      },
                      "progress": 1,
                      "created_at": "2026-10-18T02:49:57.251Z",
                      "seconds": 0.06,
                      "error": null,
                      "totals": [
                        {
                          "design": 0,
                          "wells_with_forecast": 2,
                          "wells_flagged": 0,
                          "forecast": {
                            "oil": {
                              "model_num": "M20260930-sample-O-d1",
                              "target": "novi_oil",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                399430.6,
                                593924.6,
                                724786.1
                              ],
                              "missing": [],
                              "bands": {
                                "p10": {
                                  "values": [
                                    279601.4,
                                    415747.2,
                                    507350.3
                                  ]
                                },
                                "p90": {
                                  "values": [
                                    559202.8,
                                    831494.4,
                                    1014700.6
                                  ]
                                }
                              }
                            },
                            "gas": {
                              "model_num": "M20260930-sample-G-d1",
                              "target": "novi_gas",
                              "unit": "mcf",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                753448.1,
                                1257061.7,
                                1655549.5
                              ],
                              "missing": [],
                              "bands": {
                                "p10": {
                                  "values": [
                                    527413.6,
                                    879943.2,
                                    1158884.6
                                  ]
                                },
                                "p90": {
                                  "values": [
                                    1054827.4,
                                    1759886.3,
                                    2317769.4
                                  ]
                                }
                              }
                            },
                            "water": {
                              "model_num": "M20260930-sample-W-d1",
                              "target": "novi_water",
                              "unit": "bbl",
                              "ip_days": [
                                360,
                                720,
                                1080
                              ],
                              "values": [
                                801112.9,
                                1145007.1,
                                1384582.1
                              ],
                              "missing": [],
                              "bands": {
                                "p10": {
                                  "values": [
                                    560779,
                                    801505,
                                    969207.4
                                  ]
                                },
                                "p90": {
                                  "values": [
                                    1121558.1,
                                    1603010,
                                    1938414.9
                                  ]
                                }
                              }
                            }
                          },
                          "by_date": {
                            "dates": [
                              "2027-01-01",
                              "2027-02-01",
                              "2027-03-01",
                              "2027-04-01",
                              "2027-05-01",
                              "2027-06-01",
                              "2027-07-01",
                              "2027-08-01",
                              "2027-09-01",
                              "2027-10-01",
                              "2027-11-01",
                              "2027-12-01",
                              "2028-01-01",
                              "2028-02-01",
                              "2028-03-01",
                              "2028-04-01",
                              "2028-05-01",
                              "2028-06-01",
                              "2028-07-01",
                              "2028-08-01",
                              "2028-09-01",
                              "2028-10-01",
                              "2028-11-01",
                              "2028-12-01",
                              "2029-01-01",
                              "2029-02-01",
                              "2029-03-01",
                              "2029-04-01",
                              "2029-05-01",
                              "2029-06-01",
                              "2029-07-01",
                              "2029-08-01",
                              "2029-09-01",
                              "2029-10-01",
                              "2029-11-01",
                              "2029-12-01",
                              "2030-01-01",
                              "2030-02-01",
                              "2030-03-01",
                              "2030-04-01"
                            ],
                            "horizon_days": 1080,
                            "forecast": {
                              "oil": {
                                "values": [
                                  0,
                                  24927.9,
                                  49738.3,
                                  74221.2,
                                  115916.6,
                                  159244.9,
                                  196897.8,
                                  232125.1,
                                  264329.4,
                                  293108.5,
                                  320697.4,
                                  345644.5,
                                  369810.5,
                                  392554.7,
                                  412710.1,
                                  433138.7,
                                  451950.6,
                                  470478.9,
                                  487623.2,
                                  504585.6,
                                  520853.6,
                                  535992.5,
                                  551052.7,
                                  565110.5,
                                  579136.2,
                                  592691.4,
                                  604561.6,
                                  617305.2,
                                  629271.2,
                                  641277.2,
                                  652571.5,
                                  663924.3,
                                  674973,
                                  685391.7,
                                  695889.3,
                                  705802,
                                  713262.2,
                                  718164.6,
                                  722492.4,
                                  724786.1
                                ],
                                "bands": {
                                  "p10": [
                                    0,
                                    17449.6,
                                    34816.8,
                                    51954.9,
                                    81141.6,
                                    111471.4,
                                    137828.5,
                                    162487.5,
                                    185030.5,
                                    205175.9,
                                    224488.1,
                                    241951,
                                    258867.3,
                                    274788.3,
                                    288897.1,
                                    303197,
                                    316365.4,
                                    329335.2,
                                    341336.2,
                                    353209.9,
                                    364597.6,
                                    375194.8,
                                    385736.9,
                                    395577.4,
                                    405395.4,
                                    414884,
                                    423193.1,
                                    432113.7,
                                    440489.9,
                                    448894,
                                    456800.1,
                                    464747,
                                    472481.1,
                                    479774.2,
                                    487122.5,
                                    494061.4,
                                    499283.5,
                                    502715.2,
                                    505744.7,
                                    507350.3
                                  ],
                                  "p90": [
                                    0,
                                    34899,
                                    69633.7,
                                    103909.7,
                                    162283.3,
                                    222942.9,
                                    275656.9,
                                    324975,
                                    370061.2,
                                    410351.8,
                                    448976.3,
                                    483902.2,
                                    517734.7,
                                    549576.6,
                                    577794.1,
                                    606394.1,
                                    632730.8,
                                    658670.5,
                                    682672.5,
                                    706419.9,
                                    729195,
                                    750389.5,
                                    771473.7,
                                    791154.6,
                                    810790.7,
                                    829768,
                                    846386.2,
                                    864227.3,
                                    880979.6,
                                    897788,
                                    913600.1,
                                    929493.9,
                                    944962.1,
                                    959548.4,
                                    974245,
                                    988122.8,
                                    998567.2,
                                    1005430.6,
                                    1011489.4,
                                    1014700.6
                                  ]
                                }
                              },
                              "gas": {
                                "values": [
                                  0,
                                  38834.2,
                                  79202.2,
                                  120817.3,
                                  190570,
                                  265860.2,
                                  334100.3,
                                  400545.4,
                                  463579.5,
                                  521830.2,
                                  579490.1,
                                  633179.1,
                                  686668.7,
                                  738362.3,
                                  785271.1,
                                  833936.4,
                                  879733.8,
                                  925793.4,
                                  969249.6,
                                  1013057.7,
                                  1055831.4,
                                  1096304,
                                  1137215.8,
                                  1175984.2,
                                  1215228.8,
                                  1253689.3,
                                  1287792.9,
                                  1324859.2,
                                  1360080.3,
                                  1395826.9,
                                  1429822.6,
                                  1464353.8,
                                  1498302.9,
                                  1530623.1,
                                  1563487.5,
                                  1594794,
                                  1618489,
                                  1634171.4,
                                  1648126,
                                  1655549.5
                                ],
                                "bands": {
                                  "p10": [
                                    0,
                                    27183.9,
                                    55441.5,
                                    84572.1,
                                    133399,
                                    186102.2,
                                    233870.2,
                                    280381.8,
                                    324505.7,
                                    365281.2,
                                    405643,
                                    443225.3,
                                    480668,
                                    516853.6,
                                    549689.7,
                                    583755.5,
                                    615813.6,
                                    648055.3,
                                    678474.7,
                                    709140.4,
                                    739081.9,
                                    767412.8,
                                    796051.1,
                                    823189,
                                    850660.2,
                                    877582.6,
                                    901455,
                                    927401.4,
                                    952056.2,
                                    977078.9,
                                    1000875.9,
                                    1025047.7,
                                    1048812,
                                    1071436.2,
                                    1094441.3,
                                    1116355.9,
                                    1132942.3,
                                    1143919.9,
                                    1153688.2,
                                    1158884.6
                                  ],
                                  "p90": [
                                    0,
                                    54367.9,
                                    110883.1,
                                    169144.2,
                                    266797.9,
                                    372204.2,
                                    467740.3,
                                    560763.7,
                                    649011.2,
                                    730562.2,
                                    811286.1,
                                    886450.7,
                                    961336.1,
                                    1033707.1,
                                    1099379.4,
                                    1167511,
                                    1231627.3,
                                    1296110.7,
                                    1356949.4,
                                    1418280.9,
                                    1478163.9,
                                    1534825.5,
                                    1592102.2,
                                    1646377.9,
                                    1701320.2,
                                    1755165.1,
                                    1802910.1,
                                    1854802.8,
                                    1904112.4,
                                    1954157.7,
                                    2001751.6,
                                    2050095.4,
                                    2097624,
                                    2142872.4,
                                    2188882.6,
                                    2232711.7,
                                    2265884.7,
                                    2287840.1,
                                    2307376.5,
                                    2317769.4
                                  ]
                                }
                              },
                              "water": {
                                "values": [
                                  0,
                                  73055.8,
                                  129180.7,
                                  178722.1,
                                  283318.6,
                                  374000.5,
                                  446237,
                                  510330.8,
                                  567232.1,
                                  617343,
                                  665070,
                                  708151.3,
                                  749918.6,
                                  789317,
                                  824329,
                                  859931.7,
                                  892827.7,
                                  925340.3,
                                  955526.7,
                                  985494.5,
                                  1014332.4,
                                  1041255.3,
                                  1068123.8,
                                  1093281.5,
                                  1118458.3,
                                  1142863.8,
                                  1164294.4,
                                  1187366,
                                  1209089.4,
                                  1230944.5,
                                  1251558.2,
                                  1272332.2,
                                  1292601.6,
                                  1311762.3,
                                  1331114.5,
                                  1349431.5,
                                  1363227.9,
                                  1372298.9,
                                  1380324.2,
                                  1384582.1
                                ],
                                "bands": {
                                  "p10": [
                                    0,
                                    51139,
                                    90426.6,
                                    125105.5,
                                    198323,
                                    261800.4,
                                    312366,
                                    357231.6,
                                    397062.4,
                                    432140.2,
                                    465549.1,
                                    495705.9,
                                    524942.9,
                                    552521.9,
                                    577030.2,
                                    601952.2,
                                    624979.4,
                                    647738.3,
                                    668868.7,
                                    689846.2,
                                    710032.7,
                                    728878.7,
                                    747686.7,
                                    765297.1,
                                    782920.9,
                                    800004.6,
                                    815006,
                                    831156.2,
                                    846362.5,
                                    861661.1,
                                    876090.7,
                                    890632.5,
                                    904821.1,
                                    918233.5,
                                    931780.1,
                                    944602,
                                    954259.5,
                                    960609.2,
                                    966226.9,
                                    969207.4
                                  ],
                                  "p90": [
                                    0,
                                    102278.1,
                                    180853.1,
                                    250211,
                                    396646,
                                    523600.7,
                                    624731.9,
                                    714463.1,
                                    794124.9,
                                    864280.3,
                                    931098,
                                    991411.8,
                                    1049886,
                                    1105043.8,
                                    1154060.6,
                                    1203904.5,
                                    1249958.8,
                                    1295476.4,
                                    1337737.4,
                                    1379692.4,
                                    1420065.3,
                                    1457757.4,
                                    1495373.4,
                                    1530594.1,
                                    1565841.7,
                                    1600009.3,
                                    1630012.2,
                                    1662312.4,
                                    1692725.1,
                                    1723322.3,
                                    1752181.5,
                                    1781265,
                                    1809642.2,
                                    1836467.1,
                                    1863560.2,
                                    1889204,
                                    1908518.9,
                                    1921218.4,
                                    1932453.9,
                                    1938414.9
                                  ]
                                }
                              }
                            }
                          }
                        }
                      ],
                      "links": {
                        "self": "/api/v1/plans/1532d447-e989-42ac-81c0-c708d5d278a2",
                        "wells": "/api/v1/plans/1532d447-e989-42ac-81c0-c708d5d278a2?include=wells",
                        "export": "/api/v1/plans/1532d447-e989-42ac-81c0-c708d5d278a2/export"
                      }
                    }
                  },
                  "chain": {
                    "summary": "Running its depletion chain: one well done, a wave pass running",
                    "value": {
                      "id": "4f1d2c7a-8e3b-4d6a-9c21-7b5e0a3f6d18",
                      "name": "Section 36 schedule",
                      "status": "running",
                      "pdp": true,
                      "total": 4,
                      "done": 1,
                      "designs": [
                        {
                          "index": 0,
                          "name": "Design 1",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 55.2,
                          "proppant_lb_per_ft": 2716,
                          "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                          "formations": [
                            {
                              "formation": "WOLFCAMP A",
                              "inputs": {
                                "fluid_bbl_per_ft": null,
                                "proppant_lb_per_ft": null
                              },
                              "fluid_bbl_per_ft": 54.5,
                              "proppant_lb_per_ft": 2709.5,
                              "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                            }
                          ]
                        }
                      ],
                      "decline": {
                        "eur_years": 50,
                        "terminal_decline": 0.06,
                        "b_min": 0.5,
                        "b_max": 2.5
                      },
                      "depletion_chain": {
                        "applied": true,
                        "reason": null,
                        "features": [
                          "novi_spacing_sum_prior_depletion_impact"
                        ],
                        "buckets": 4,
                        "waves": 3,
                        "planned_parents": 3,
                        "neighbor_production": "history",
                        "extension": null
                      },
                      "progress": 0.775,
                      "steps": {
                        "spacing": 0,
                        "calc": 0,
                        "forecast": 0,
                        "eur": 0,
                        "chain": 1
                      },
                      "created_at": "2026-10-22T14:05:31.204Z",
                      "seconds": 0.41,
                      "error": null,
                      "totals": null,
                      "links": {
                        "self": "/api/v1/plans/4f1d2c7a-8e3b-4d6a-9c21-7b5e0a3f6d18",
                        "wells": "/api/v1/plans/4f1d2c7a-8e3b-4d6a-9c21-7b5e0a3f6d18?include=wells",
                        "export": "/api/v1/plans/4f1d2c7a-8e3b-4d6a-9c21-7b5e0a3f6d18/export"
                      }
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "patch": {
        "operationId": "updatePlan",
        "tags": [
          "Plans"
        ],
        "summary": "Rename or save a plan",
        "description": "Renames a plan, saves or unsaves it, or both, also while it runs. `name` is null to clear it, or 1 to 100 characters. Renaming works without a state store; `saved` needs one.\n\n**Errors.**\n\n- 400: unknown fields, an empty object or an invalid value.\n- 404: a missing plan or another tenant's.\n- 409 `conflict`: `saved` without a state store, or a Legacy Forecast, which is read only (`details.reason` `plan_read_only`).\n- 409: a write that lost to a racing heartbeat three times; retry it.\n\n**Documents.** Attached documents follow the plan's expiry.\n\n**Retention.** With a state store, an unsaved plan is kept for the server's scratch period after it is made (90 days unless the server sets another; `storage.expires_at` says when) and deleted within a minute of `expires_at`; a saved plan is kept until deleted. Saving clears `expires_at`; unsaving starts a new scratch period. A deleted plan is gone from the API at once, its shares revoked and its attached documents deleted.",
        "requestBody": {
          "required": true,
          "description": "At least one change.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatePlanBody"
              },
              "example": {
                "saved": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The plan with storage, null without a store.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdatedPlan"
                },
                "example": {
                  "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                  "name": "Section 36 infill",
                  "status": "done",
                  "pdp": true,
                  "total": 2,
                  "done": 2,
                  "designs": [
                    {
                      "index": 0,
                      "name": "Recent median",
                      "inputs": {
                        "fluid_bbl_per_ft": null,
                        "proppant_lb_per_ft": null
                      },
                      "fluid_bbl_per_ft": 55.2,
                      "proppant_lb_per_ft": 2716,
                      "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                      "formations": [
                        {
                          "formation": "WOLFCAMP A",
                          "inputs": {
                            "fluid_bbl_per_ft": null,
                            "proppant_lb_per_ft": null
                          },
                          "fluid_bbl_per_ft": 54.5,
                          "proppant_lb_per_ft": 2709.5,
                          "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                        }
                      ]
                    },
                    {
                      "index": 1,
                      "name": "Upsized",
                      "inputs": {
                        "fluid_bbl_per_ft": 60,
                        "proppant_lb_per_ft": 3000
                      },
                      "fluid_bbl_per_ft": 60,
                      "proppant_lb_per_ft": 3000,
                      "completions_source": "input",
                      "formations": [
                        {
                          "formation": "WOLFCAMP A",
                          "inputs": {
                            "fluid_bbl_per_ft": 60,
                            "proppant_lb_per_ft": 3000
                          },
                          "fluid_bbl_per_ft": 60,
                          "proppant_lb_per_ft": 3000,
                          "completions_source": "input"
                        }
                      ]
                    }
                  ],
                  "decline": {
                    "eur_years": 50,
                    "terminal_decline": 0.06,
                    "b_min": 0.5,
                    "b_max": 2.5
                  },
                  "progress": 1,
                  "created_at": "2026-10-17T21:59:49.718Z",
                  "seconds": 0.08,
                  "error": null,
                  "totals": [
                    {
                      "design": 0,
                      "wells_with_forecast": 2,
                      "wells_flagged": 0,
                      "forecast": {
                        "oil": {
                          "model_num": "M20260930-sample-O-d1",
                          "target": "novi_oil",
                          "unit": "bbl",
                          "ip_days": [
                            360,
                            720,
                            1080
                          ],
                          "values": [
                            398361.2,
                            592769.9,
                            723038.3
                          ],
                          "missing": []
                        },
                        "gas": {
                          "model_num": "M20260930-sample-G-d1",
                          "target": "novi_gas",
                          "unit": "mcf",
                          "ip_days": [
                            360,
                            720,
                            1080
                          ],
                          "values": [
                            752385.2,
                            1255796.5,
                            1652522.2
                          ],
                          "missing": []
                        },
                        "water": {
                          "model_num": "M20260930-sample-W-d1",
                          "target": "novi_water",
                          "unit": "bbl",
                          "ip_days": [
                            360,
                            720,
                            1080
                          ],
                          "values": [
                            799833.1,
                            1143571.4,
                            1382059
                          ],
                          "missing": []
                        }
                      },
                      "eur": {
                        "oil": {
                          "value": 1712047.8,
                          "days": 18240,
                          "wells": 2
                        },
                        "gas": {
                          "value": 6364416.5,
                          "days": 18240,
                          "wells": 2
                        },
                        "boe": {
                          "value": 2772783.9,
                          "wells": 2
                        }
                      }
                    },
                    {
                      "design": 1,
                      "wells_with_forecast": 2,
                      "wells_flagged": 0,
                      "forecast": {
                        "oil": {
                          "model_num": "M20260930-sample-O-d1",
                          "target": "novi_oil",
                          "unit": "bbl",
                          "ip_days": [
                            360,
                            720,
                            1080
                          ],
                          "values": [
                            416334,
                            619513.8,
                            755659.5
                          ],
                          "missing": []
                        },
                        "gas": {
                          "model_num": "M20260930-sample-G-d1",
                          "target": "novi_gas",
                          "unit": "mcf",
                          "ip_days": [
                            360,
                            720,
                            1080
                          ],
                          "values": [
                            786330.4,
                            1312454.1,
                            1727078.8
                          ],
                          "missing": []
                        },
                        "water": {
                          "model_num": "M20260930-sample-W-d1",
                          "target": "novi_water",
                          "unit": "bbl",
                          "ip_days": [
                            360,
                            720,
                            1080
                          ],
                          "values": [
                            843073.9,
                            1202322.8,
                            1451570.2
                          ],
                          "missing": []
                        }
                      },
                      "eur": {
                        "oil": {
                          "value": 1789297.5,
                          "days": 18240,
                          "wells": 2
                        },
                        "gas": {
                          "value": 6651556.6,
                          "days": 18240,
                          "wells": 2
                        },
                        "boe": {
                          "value": 2897890.3,
                          "wells": 2
                        }
                      }
                    }
                  ],
                  "links": {
                    "self": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                    "wells": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630?include=wells",
                    "export": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630/export"
                  },
                  "storage": {
                    "tenant": "example",
                    "saved": true,
                    "expires_at": null,
                    "created_at": "2026-01-01T00:00:00Z",
                    "updated_at": "2026-01-01T00:00:00Z",
                    "created_by": null,
                    "shares": 0
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      },
      "delete": {
        "operationId": "deletePlan",
        "tags": [
          "Plans"
        ],
        "summary": "Delete a plan",
        "description": "Deletes a plan: revokes its shares, deletes its attached saved documents, then drops the plan and its results. A running plan stops after its chunks in flight. It doesn't wait for a restarted server to finish reading its stored plans.\n\n**Exports.** Exports of the plan aren't cancelled: each keeps the plan until its file is written, and the file stays until it expires.\n\n**Errors.**\n\n- 409 with `details.saved` and `details.shares`: `unless=saved` on a saved or shared plan.\n- 409, which can be retried: a plan running on another server, or one that keeps changing while it is deleted.\n- 409 `conflict` with `details.reason` `plan_read_only`: a Legacy Forecast (`origin.engine` `fe`), which is never deleted.",
        "parameters": [
          {
            "name": "unless",
            "in": "query",
            "description": "`saved`: delete the plan only if it isn't saved and has no active share link; otherwise answer 409 `conflict` with `details` `{id, saved, shares}` and leave the plan, its shares and its documents as they were.\n\n`shares` counts active share links; no other 409 here carries `saved`. Use it to drop a plan you believe is unsaved without losing a save or share made meanwhile, as from another tab: the plan is marked deleting only if its metadata hasn't changed since the check, so a save or share that lands first wins. Without a state store no plan is saved, so it deletes as without it. Another value, an empty one or `unless` twice is a 400.",
            "schema": {
              "type": "string",
              "enum": [
                "saved"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedPlan"
                },
                "example": {
                  "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                  "deleted": true
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/plans/{id}/shares": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        }
      ],
      "post": {
        "operationId": "createPlanShare",
        "tags": [
          "Plans"
        ],
        "summary": "Share a completed plan",
        "description": "Creates a read link to a done plan and saves the plan. Copy the returned token now: it is returned only once, and only its SHA-256 is stored.\n\n**The body.** `visibility` records the intended audience, `link` (anyone holding the URL) or `tenant` (the plan's tenant), and doesn't change who can read: any user of the plan's tenant who holds the token can read it, and a user of another tenant gets 404. `expires_in_days` is a whole number from 1 to 365; absent, the link never expires.\n\n**Errors.** 400 for an invalid or unknown field; 404 for a missing plan or another tenant's; 409 without a state store or for a plan that isn't done.",
        "requestBody": {
          "required": true,
          "description": "Link audience and optional lifetime.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePlanShareBody"
              },
              "example": {
                "visibility": "link",
                "expires_in_days": 7
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The token, returned only here.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatedPlanShare"
                },
                "example": {
                  "id": "00000000-0000-4000-8000-000000000001",
                  "visibility": "link",
                  "created_at": "2026-01-01T00:00:00Z",
                  "expires_at": null,
                  "revoked_at": null,
                  "token": "AAAAAAAAAAAAAAAAAAAAAA",
                  "plan": {
                    "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                    "name": "Section 36 infill",
                    "model_set": "default"
                  },
                  "links": {
                    "self": "/api/v1/shares/AAAAAAAAAAAAAAAAAAAAAA"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      },
      "get": {
        "operationId": "listPlanShares",
        "tags": [
          "Plans"
        ],
        "summary": "List a plan shares",
        "description": "List share metadata newest first, including revoked and expired shares, never tokens. Use this to manage links. A missing or other-tenant plan is 404; no state store is 409.",
        "responses": {
          "200": {
            "description": "Share metadata.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanShareList"
                },
                "example": {
                  "shares": [
                    {
                      "id": "00000000-0000-4000-8000-000000000001",
                      "visibility": "link",
                      "created_at": "2026-01-01T00:00:00Z",
                      "expires_at": null,
                      "revoked_at": null
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/plans/{id}/shares/{share_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        },
        {
          "name": "share_id",
          "in": "path",
          "required": true,
          "description": "Share id from createPlanShare or listPlanShares.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "delete": {
        "operationId": "revokePlanShare",
        "tags": [
          "Plans"
        ],
        "summary": "Revoke a plan share",
        "description": "Disable a share immediately. Revoking it again also returns 204. An unknown plan or share, or another tenant, is 404. No state store or repeated concurrent changes is 409; retry a concurrent change.",
        "responses": {
          "204": {
            "description": "Revoked, including an already revoked share.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/shares/{token}": {
      "parameters": [
        {
          "name": "token",
          "in": "path",
          "required": true,
          "description": "The secret 22-character base64url token returned when creating the share.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "operationId": "getShare",
        "tags": [
          "Plans"
        ],
        "summary": "Open a shared plan",
        "description": "Reads a share and its stored plan view, without the plan's forecast results, in the share's model set. Any user of the plan's tenant who holds the token can read a share of either visibility.\n\n**Errors.** 404 (Share link not found or no longer active) for an unknown, revoked, expired, unserved or other-tenant share, or a deleted plan; 409 without a state store.",
        "responses": {
          "200": {
            "description": "Share metadata, stored plan and its model set.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SharedPlan"
                },
                "example": {
                  "share": {
                    "id": "00000000-0000-4000-8000-000000000001",
                    "visibility": "link",
                    "created_at": "2026-01-01T00:00:00Z",
                    "expires_at": null
                  },
                  "plan": {
                    "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                    "name": "Section 36 infill",
                    "status": "done",
                    "pdp": true,
                    "total": 2,
                    "done": 2,
                    "designs": [
                      {
                        "index": 0,
                        "name": "Recent median",
                        "inputs": {
                          "fluid_bbl_per_ft": null,
                          "proppant_lb_per_ft": null
                        },
                        "fluid_bbl_per_ft": 55.2,
                        "proppant_lb_per_ft": 2716,
                        "completions_source": "median of 1572 wells online 2026-04-04 to 2026-09-30",
                        "formations": [
                          {
                            "formation": "WOLFCAMP A",
                            "inputs": {
                              "fluid_bbl_per_ft": null,
                              "proppant_lb_per_ft": null
                            },
                            "fluid_bbl_per_ft": 54.5,
                            "proppant_lb_per_ft": 2709.5,
                            "completions_source": "median of 372 WOLFCAMP A wells online 2026-04-04 to 2026-09-30"
                          }
                        ]
                      },
                      {
                        "index": 1,
                        "name": "Upsized",
                        "inputs": {
                          "fluid_bbl_per_ft": 60,
                          "proppant_lb_per_ft": 3000
                        },
                        "fluid_bbl_per_ft": 60,
                        "proppant_lb_per_ft": 3000,
                        "completions_source": "input",
                        "formations": [
                          {
                            "formation": "WOLFCAMP A",
                            "inputs": {
                              "fluid_bbl_per_ft": 60,
                              "proppant_lb_per_ft": 3000
                            },
                            "fluid_bbl_per_ft": 60,
                            "proppant_lb_per_ft": 3000,
                            "completions_source": "input"
                          }
                        ]
                      }
                    ],
                    "decline": {
                      "eur_years": 50,
                      "terminal_decline": 0.06,
                      "b_min": 0.5,
                      "b_max": 2.5
                    },
                    "progress": 1,
                    "created_at": "2026-10-17T21:59:49.718Z",
                    "seconds": 0.08,
                    "error": null,
                    "totals": [
                      {
                        "design": 0,
                        "wells_with_forecast": 2,
                        "wells_flagged": 0,
                        "forecast": {
                          "oil": {
                            "model_num": "M20260930-sample-O-d1",
                            "target": "novi_oil",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              398361.2,
                              592769.9,
                              723038.3
                            ],
                            "missing": []
                          },
                          "gas": {
                            "model_num": "M20260930-sample-G-d1",
                            "target": "novi_gas",
                            "unit": "mcf",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              752385.2,
                              1255796.5,
                              1652522.2
                            ],
                            "missing": []
                          },
                          "water": {
                            "model_num": "M20260930-sample-W-d1",
                            "target": "novi_water",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              799833.1,
                              1143571.4,
                              1382059
                            ],
                            "missing": []
                          }
                        },
                        "eur": {
                          "oil": {
                            "value": 1712047.8,
                            "days": 18240,
                            "wells": 2
                          },
                          "gas": {
                            "value": 6364416.5,
                            "days": 18240,
                            "wells": 2
                          },
                          "boe": {
                            "value": 2772783.9,
                            "wells": 2
                          }
                        }
                      },
                      {
                        "design": 1,
                        "wells_with_forecast": 2,
                        "wells_flagged": 0,
                        "forecast": {
                          "oil": {
                            "model_num": "M20260930-sample-O-d1",
                            "target": "novi_oil",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              416334,
                              619513.8,
                              755659.5
                            ],
                            "missing": []
                          },
                          "gas": {
                            "model_num": "M20260930-sample-G-d1",
                            "target": "novi_gas",
                            "unit": "mcf",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              786330.4,
                              1312454.1,
                              1727078.8
                            ],
                            "missing": []
                          },
                          "water": {
                            "model_num": "M20260930-sample-W-d1",
                            "target": "novi_water",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              843073.9,
                              1202322.8,
                              1451570.2
                            ],
                            "missing": []
                          }
                        },
                        "eur": {
                          "oil": {
                            "value": 1789297.5,
                            "days": 18240,
                            "wells": 2
                          },
                          "gas": {
                            "value": 6651556.6,
                            "days": 18240,
                            "wells": 2
                          },
                          "boe": {
                            "value": 2897890.3,
                            "wells": 2
                          }
                        }
                      }
                    ],
                    "links": {
                      "self": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                      "wells": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630?include=wells",
                      "export": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630/export"
                    }
                  },
                  "model_set": "default"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        },
        "parameters": []
      }
    },
    "/saved/{collection}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/SavedCollection"
        }
      ],
      "get": {
        "operationId": "listSavedDocs",
        "tags": [
          "Saved documents"
        ],
        "summary": "List saved documents",
        "description": "List this tenant documents in one collection, newest updated_at first. Use include=body to read content too, and plan_id to find a plan draft. A private document answers only its creator. Unknown collection or include, invalid plan_id, limit or cursor is 400; an unserved tenant is 404; no state store is 409.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Page size, 1-100.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "name": "include",
            "in": "query",
            "description": "body includes each document body; other or duplicate names are 400.",
            "schema": {
              "type": "string",
              "enum": [
                "body"
              ]
            }
          },
          {
            "name": "plan_id",
            "in": "query",
            "description": "Only documents attached to this plan UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Documents and next cursor.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SavedDocList"
                },
                "example": {
                  "items": [
                    {
                      "id": "00000000-0000-4000-8000-000000000002",
                      "name": "Draft",
                      "visibility": "tenant",
                      "plan_id": null,
                      "created_at": "2026-01-01T00:00:00Z",
                      "updated_at": "2026-01-01T00:00:00Z",
                      "etag": "\"opaque-etag\""
                    }
                  ],
                  "next_cursor": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        }
      },
      "post": {
        "operationId": "createSavedDoc",
        "tags": [
          "Saved documents"
        ],
        "summary": "Save a document",
        "description": "Saves a filter set, completion design, type curve, view or settings object.\n\n**The body.** `name` is 1 to 100 characters; `visibility` defaults to `tenant`, and a private document answers only its creator (anyone else gets 404 and doesn't see it listed). `body` is JSON of at most 65,536 UTF-8 bytes, or with `plan_id` up to the 64 MB request body. `plan_id` attaches it to a plan as a draft: it follows the plan's retention, save and unsave, and is deleted with the plan.\n\n**Retries.** The same Idempotency-Key and body answer the first document; keys are scoped to the tenant, the signed-in creator and the collection.\n\n**Errors.** 400 for an invalid collection, field, name, visibility, body or `plan_id`; 404 for a missing plan or another tenant's; 409 without a state store or for an Idempotency-Key reused with another body.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Document content and optional plan attachment.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SavedDocBody"
              },
              "example": {
                "name": "Draft",
                "body": {}
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Saved document and ETag.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/VersionETag"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SavedDoc"
                },
                "example": {
                  "id": "00000000-0000-4000-8000-000000000002",
                  "collection": "views",
                  "name": "Draft",
                  "visibility": "tenant",
                  "plan_id": null,
                  "created_at": "2026-01-01T00:00:00Z",
                  "updated_at": "2026-01-01T00:00:00Z",
                  "created_by": null,
                  "etag": "\"opaque-etag\"",
                  "body": {
                    "pads": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "No state store, or the Idempotency-Key was already used with another body; or, with Redis, the first request with this Idempotency-Key is still being made (after a 30 s wait); retry shortly with the same key.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "conflict",
                    "message": "This Idempotency-Key was already used with a different request body; send a new key for a new request, or the same body for the first request's result",
                    "details": {
                      "field": "Idempotency-Key"
                    }
                  },
                  "request_id": "1d6f3a8c-5e2b-4c97-8a0d-7b4e9f2c6a13"
                }
              }
            }
          },
          "413": {
            "description": "The request body is over 64 MB.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "description": "With Redis, the Redis that keeps Idempotency-Key records isn't answering; retry with the same key.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/saved/{collection}/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/SavedCollection"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Document UUID.",
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "getSavedDoc",
        "tags": [
          "Saved documents"
        ],
        "summary": "Read a saved document",
        "description": "Read content and its ETag for editing. Unknown collection is 400; unknown, expired-with-plan or other-tenant document is 404; no state store is 409. A private document answers only its creator.",
        "responses": {
          "200": {
            "description": "Document.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/VersionETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SavedDoc"
                },
                "example": {
                  "id": "00000000-0000-4000-8000-000000000002",
                  "collection": "views",
                  "name": "Draft",
                  "visibility": "tenant",
                  "plan_id": null,
                  "created_at": "2026-01-01T00:00:00Z",
                  "updated_at": "2026-01-01T00:00:00Z",
                  "created_by": null,
                  "etag": "\"opaque-etag\"",
                  "body": {
                    "pads": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        },
        "parameters": []
      },
      "put": {
        "operationId": "replaceSavedDoc",
        "tags": [
          "Saved documents"
        ],
        "summary": "Replace a saved document",
        "description": "Replaces a document's name, visibility, body and plan attachment, given its current ETag in `If-Match`. An omitted `visibility` becomes `tenant`; an omitted `plan_id` detaches it.\n\n**Errors.** 400 for an invalid collection or content (as createSavedDoc checks them), a missing `If-Match`, or a private `visibility` from anyone but the creator; 404 for an unknown or other-tenant document or plan, or another user's private document; 409 without a state store, or `conflict` for a stale `If-Match`, with `details.etag` the current ETag: read and reconcile before retrying.",
        "parameters": [
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "description": "Current document etag, including quotes.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Replacement content.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SavedDocBody"
              },
              "example": {
                "name": "Draft",
                "body": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated document.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/VersionETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SavedDoc"
                },
                "example": {
                  "id": "00000000-0000-4000-8000-000000000002",
                  "collection": "views",
                  "name": "Draft",
                  "visibility": "tenant",
                  "plan_id": null,
                  "created_at": "2026-01-01T00:00:00Z",
                  "updated_at": "2026-01-01T00:00:00Z",
                  "created_by": null,
                  "etag": "\"opaque-etag\"",
                  "body": {
                    "pads": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "description": "The request body is over 64 MB.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        }
      },
      "delete": {
        "operationId": "deleteSavedDoc",
        "tags": [
          "Saved documents"
        ],
        "summary": "Delete a saved document",
        "description": "Delete a document from the request tenant. Unknown collection is 400; unknown or other-tenant document is 404; no state store is 409. If-Match is optional: a stale one is a 409 conflict with details.etag set to the current ETag, and nothing is deleted; without it, the document is deleted whatever its ETag.",
        "parameters": [
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "The document's current etag, including quotes. Absent: deleted without the check.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        }
      }
    },
    "/plans/{id}/stats": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        }
      ],
      "get": {
        "operationId": "getPlanStats",
        "tags": [
          "Plans"
        ],
        "summary": "Summarize a plan's wells",
        "description": "The distribution of one per-well metric over a plan's wells under one design, without downloading the wells: how many have a value, min, max, mean, quantiles and a histogram, as PlanStats describes them.\n\n**What it measures.** `eur_boe` by default on a plan made with `eur: true`, else `cum_boe` at ip_day 1080; values are rounded to 0.1, in `unit`. On a plan made with scenarios, every figure pools all its scenarios' wells unless `scenario` picks one; `group_by=scenario` measures each beside that pooled top level.\n\n**Quantiles and bins.** Quantiles interpolate linearly between the closest ranks (NumPy's default, Hyndman and Fan type 7): q10 is the low end, 10% of wells below it. They are the spread across wells, not a forecast's uncertainty: P10/P90 bands (Novi's P10 is the low curve, the reverse of SPE PRMS) are per well, from `bands: true`. The histogram has `bins` equal-width bins from min to max, each from its lower edge up to its upper one (the last includes max); when every value is the same it is one bin.\n\n**While it runs.** The figures cover the wells finished so far, with `partial: true`, `Retry-After: 1` and no `ETag`. A done plan's answer carries an `ETag`; send it as `If-None-Match` for a 304. A failed plan answers 409.",
        "parameters": [
          {
            "name": "metric",
            "in": "query",
            "description": "The metric: eur_boe by default on a plan with EUR, else cum_boe.\n\nPer-well metrics: `eur_oil` (bbl), `eur_gas` (mcf) and `eur_boe` (BOE) are each well's EUR and need a plan made with `eur: true` (400 otherwise); `cum_oil`, `cum_gas` and `cum_boe` are the forecast's cumulative volume at `ip_day`. BOE is oil + gas / 6, only for wells with both.",
            "schema": {
              "type": "string",
              "enum": [
                "eur_boe",
                "eur_oil",
                "eur_gas",
                "cum_boe",
                "cum_oil",
                "cum_gas"
              ]
            }
          },
          {
            "name": "design",
            "in": "query",
            "description": "the design whose forecasts are measured, as its index in the plan's `designs`; 400 past the last one.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9,
              "default": 0
            }
          },
          {
            "name": "ip_day",
            "in": "query",
            "description": "for a cum_ metric, the ip_day (days since first production) whose cumulative volume is measured: one of GET /dataset `ip_days`, default 1080 (3 years). 400 with an eur_ metric.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1080
            }
          },
          {
            "name": "bins",
            "in": "query",
            "description": "Histogram bins.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "include",
            "in": "query",
            "description": "`values` adds every well's value, ascending (ties by plan index), with its plan index: for probit plots, and for linking a point to its well. Up to the plan's wells (GET /dataset `limits.plan_wells`).",
            "schema": {
              "type": "string",
              "enum": [
                "values"
              ]
            }
          },
          {
            "name": "quantiles",
            "in": "query",
            "description": "Which quantiles to return, comma-separated: whole percentiles 1 to 99, at most 9 different ones, as 10,25,50,75,90 for a box plot; `quantiles` then holds exactly `q10`, `q25` and so on. Quantiles of wells' values (type 7, q10 the low end), not P-level bands. Absent: q10, q50 and q90.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "group_by",
            "in": "query",
            "description": "Also measure each group of wells: `design`, `formation`, `scenario` or `pad`. The top-level figures stay those of `design`, 0 by default.\n\n- `design`: every design of the plan; a 400 with the `design` parameter.\n- `formation`: each well's target formation, wells without one as `key: null`.\n- `scenario`: each scenario of a plan made with them; a 400 on another plan and with the `scenario` parameter.\n- `pad`: each stored pad key (after scenario scoping), wells without one as `null`, never folded into `Other`. A plan whose wells name no pads is a 400: send `wells[].pad`.\n\nEach group has its own counts, min, max, mean, quantiles and histogram, and `values` with `include=values`, all on the same `edges` (for `formation` and `scenario` the top-level edges, for `design` every design's), so groups plot side by side. PlanStats `groups` gives their order; `design`, `formation` and `scenario` give at most 50 groups, the rest summed in one `Other` row with `others`.",
            "schema": {
              "type": "string",
              "enum": [
                "design",
                "formation",
                "scenario",
                "pad"
              ]
            }
          },
          {
            "name": "normalize_lateral_ft",
            "in": "query",
            "description": "Scale each well's value to this lateral length before measuring: value × normalize_lateral_ft / its lateral_length_ft, so 1000 gives values per 1,000 ft of lateral. Every figure is then normalised, the response echoes it, and `unit` still names the volume. 100 to 20,000.",
            "schema": {
              "type": "number",
              "minimum": 100,
              "maximum": 20000
            }
          },
          {
            "name": "scenario",
            "in": "query",
            "description": "Measure one scenario of a plan made with them: every figure, the histogram's bins and any `group_by=formation` or `group_by=design` groups cover only its wells, and the response echoes the name.\n\nSend the name exactly as the plan's `scenarios` list it, URL-encoded: `660 ft` is `scenario=660%20ft`. With `include=values`, `index` stays the well's index in the whole plan, so a point still links to its well. While the plan runs, the figures cover the scenario's wells finished so far.\n\nAn empty name, or one the plan doesn't have, is a 400 whose `details.scenarios` lists the plan's scenarios (empty on a plan without them, where any name is a 400). A name over 60 characters is a 400 without the list. With `group_by=scenario` it is a 400 on `group_by`: `scenario` picks one, so leave `group_by=scenario` out.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The distribution.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanStats"
                },
                "examples": {
                  "stats": {
                    "summary": "BOE EUR, bins=5",
                    "value": {
                      "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                      "design": 0,
                      "metric": "eur_boe",
                      "ip_day": null,
                      "unit": "BOE",
                      "partial": false,
                      "wells": 8,
                      "missing": 0,
                      "min": 630789.9,
                      "max": 1052441.7,
                      "mean": 769606.2,
                      "quantiles": {
                        "q10": 668744.1,
                        "q50": 720752.5,
                        "q90": 899548.7
                      },
                      "histogram": {
                        "edges": [
                          630789.9,
                          715120.3,
                          799450.6,
                          883781,
                          968111.4,
                          1052441.7
                        ],
                        "counts": [
                          4,
                          1,
                          2,
                          0,
                          1
                        ]
                      }
                    }
                  },
                  "groups": {
                    "summary": "include=values, quartiles and group_by=design, bins=4",
                    "value": {
                      "id": "6673c71e-730d-4028-951d-777395ca33bd",
                      "design": 0,
                      "metric": "eur_boe",
                      "ip_day": null,
                      "unit": "BOE",
                      "partial": false,
                      "wells": 2,
                      "missing": 0,
                      "min": 1370295,
                      "max": 1401361.3,
                      "mean": 1385828.1,
                      "quantiles": {
                        "q25": 1378061.6,
                        "q50": 1385828.1,
                        "q75": 1393594.7
                      },
                      "histogram": {
                        "edges": [
                          1370295,
                          1378061.6,
                          1385828.1,
                          1393594.7,
                          1401361.3
                        ],
                        "counts": [
                          1,
                          0,
                          0,
                          1
                        ]
                      },
                      "values": {
                        "index": [
                          1,
                          0
                        ],
                        "value": [
                          1370295,
                          1401361.3
                        ]
                      },
                      "group_by": "design",
                      "groups": [
                        {
                          "key": 0,
                          "wells": 2,
                          "missing": 0,
                          "min": 1370295,
                          "max": 1401361.3,
                          "mean": 1385828.1,
                          "quantiles": {
                            "q25": 1378061.6,
                            "q50": 1385828.1,
                            "q75": 1393594.7
                          },
                          "histogram": {
                            "edges": [
                              1370295,
                              1393870.5,
                              1417446,
                              1441021.6,
                              1464597.1
                            ],
                            "counts": [
                              1,
                              1,
                              0,
                              0
                            ]
                          },
                          "values": {
                            "index": [
                              1,
                              0
                            ],
                            "value": [
                              1370295,
                              1401361.3
                            ]
                          }
                        },
                        {
                          "key": 1,
                          "wells": 2,
                          "missing": 0,
                          "min": 1432121.5,
                          "max": 1464597.1,
                          "mean": 1448359.3,
                          "quantiles": {
                            "q25": 1440240.4,
                            "q50": 1448359.3,
                            "q75": 1456478.2
                          },
                          "histogram": {
                            "edges": [
                              1370295,
                              1393870.5,
                              1417446,
                              1441021.6,
                              1464597.1
                            ],
                            "counts": [
                              0,
                              0,
                              1,
                              1
                            ]
                          },
                          "values": {
                            "index": [
                              1,
                              0
                            ],
                            "value": [
                              1432121.5,
                              1464597.1
                            ]
                          }
                        }
                      ]
                    }
                  },
                  "scenarios": {
                    "summary": "group_by=scenario: two spacings in one plan, bins=4",
                    "value": {
                      "id": "bdaa881e-5165-47bf-95a2-c75fd33b6cae",
                      "design": 0,
                      "metric": "eur_boe",
                      "ip_day": null,
                      "unit": "BOE",
                      "partial": false,
                      "wells": 5,
                      "missing": 0,
                      "min": 1253039.2,
                      "max": 1467754,
                      "mean": 1402126.2,
                      "quantiles": {
                        "q10": 1308474.3,
                        "q50": 1435398.6,
                        "q90": 1465777.3
                      },
                      "histogram": {
                        "edges": [
                          1253039.2,
                          1306717.9,
                          1360396.6,
                          1414075.3,
                          1467754
                        ],
                        "counts": [
                          1,
                          0,
                          1,
                          3
                        ]
                      },
                      "group_by": "scenario",
                      "groups": [
                        {
                          "key": "1,320 ft",
                          "wells": 2,
                          "missing": 0,
                          "min": 1462812.4,
                          "max": 1467754,
                          "mean": 1465283.2,
                          "quantiles": {
                            "q10": 1463306.5,
                            "q50": 1465283.2,
                            "q90": 1467259.8
                          },
                          "histogram": {
                            "edges": [
                              1253039.2,
                              1306717.9,
                              1360396.6,
                              1414075.3,
                              1467754
                            ],
                            "counts": [
                              0,
                              0,
                              0,
                              2
                            ]
                          }
                        },
                        {
                          "key": "880 ft",
                          "wells": 3,
                          "missing": 0,
                          "min": 1253039.2,
                          "max": 1435398.6,
                          "mean": 1360021.6,
                          "quantiles": {
                            "q10": 1280756.8,
                            "q50": 1391627,
                            "q90": 1426644.3
                          },
                          "histogram": {
                            "edges": [
                              1253039.2,
                              1306717.9,
                              1360396.6,
                              1414075.3,
                              1467754
                            ],
                            "counts": [
                              1,
                              0,
                              1,
                              1
                            ]
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/plans/{id}/checks": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        }
      ],
      "get": {
        "operationId": "getPlanChecks",
        "tags": [
          "Plans"
        ],
        "summary": "Count a plan's flagged wells by input and side",
        "description": "A plan's warnings counted per design and, on a plan made with scenarios, per scenario: how many wells were checked, flagged and given context, and which inputs flagged them on which side.\n\n**Counts.** PlanChecksEntry describes each count; they match GET /plans/{id} `totals`, and `wells` includes `per_well_errors` failures. `context` flags nothing: it describes neighboring production outside training.\n\n**Rows.** A row is a feature, side and model_num (missing by feature, unknown_formation by value), counting each well once, as PlanCheckRow describes it. Unavailable checks add nothing, and an empty list is `[]`.\n\n- Scenarios come in the plan's order, designs in index order within each.\n- Lists sort by `wells` descending, then feature or value by code point, then below before above, then model_num by code point.\n- For the full per-well list beyond `well_indexes`, read GET /plans/{id}?include=wells&fields=checks&design=0, with `design` set to the entry's index.\n\n**While it runs.** Only finished wells count, with `Retry-After: 1` and no ETag. A done plan's answer carries an ETag; send `If-None-Match` for a 304. A failed plan answers 409.",
        "parameters": [
          {
            "name": "design",
            "in": "query",
            "description": "A design index; absent: every design. Out of range is a 400.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "scenario",
            "in": "query",
            "description": "On a plan made with scenarios: a scenario name; absent: one entry per scenario. A name the plan lacks is a 400 listing its scenarios.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The checks rollup; an ETag when done, Retry-After: 1 while running.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanChecks"
                },
                "example": {
                  "plan_id": "e287ce51-430c-4871-87c2-e9c4191fb412",
                  "status": "done",
                  "checks": [
                    {
                      "design": 0,
                      "wells": 12,
                      "wells_checked": 11,
                      "wells_flagged": 3,
                      "wells_context": 1,
                      "wells_unchecked": 1,
                      "out_of_range": [
                        {
                          "feature": "novi_lateral_length",
                          "side": "above",
                          "wells": 2,
                          "low": 4449,
                          "high": 16555,
                          "min": 18000,
                          "max": 21000,
                          "model_num": "M-O",
                          "well_indexes": [
                            0,
                            4
                          ]
                        },
                        {
                          "feature": "novi_calc_proppant_per_length",
                          "side": "below",
                          "wells": 1,
                          "low": 1200,
                          "high": 3200,
                          "min": 900,
                          "max": 900,
                          "model_num": "M-O",
                          "well_indexes": [
                            7
                          ]
                        }
                      ],
                      "missing": [
                        {
                          "feature": "novi_bvi_avg",
                          "wells": 1,
                          "well_indexes": [
                            7
                          ]
                        }
                      ],
                      "unknown_formation": [],
                      "context": [
                        {
                          "feature": "novi_spacing_sum_prior_depletion_impact",
                          "side": "above",
                          "wells": 1,
                          "low": 0,
                          "high": 359344.22,
                          "min": 641223.55,
                          "max": 641223.55,
                          "model_num": "M-O",
                          "well_indexes": [
                            2
                          ]
                        }
                      ]
                    }
                  ]
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/plans/{id}/rollup": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        }
      ],
      "get": {
        "operationId": "getPlanRollup",
        "tags": [
          "Plans"
        ],
        "summary": "Sum a plan's oil, gas and water by pad and zone",
        "description": "One design's oil, gas and water at one ip_day, summed for a plan by pad and by landing zone (formation) in each pad, without downloading the wells. Every pad is listed, without paging, as PlanRollup describes; a plan whose wells name no pads answers one `key: null` pad.\n\n**Sums.** Wells and streams count as GET /plans/{id} `totals` counts them: a well counts when its forecast under the design isn't an error, and a stream sums its wells whose stream forecast isn't an error, so a well without a water forecast is left out of water only. A well without a value at `ip_day` adds 0. Each value is summed unrounded and rounded once to 0.1.\n\n- Counts add up exactly: formations to their pad and pads to `totals`, `wells_flagged` with null as 0.\n- Values can differ from the sum of their parts by rounding: a pad from its N formations by up to 0.05 × (N + 1), and `totals` from its P pads by up to 0.05 × (P + 1).\n- On a done plan the `totals` row equals GET /plans/{id} `totals` for the same design and scenario wherever those have a value at `ip_day`: `wells_with_forecast`, `wells_flagged` and each stream's value.\n\n**EUR.** On a plan made with `eur: true`, every row has `eur` (PlanRollupEur), rounded and adding up as the values do. It doesn't change with `ip_day`, so a done plan's `totals` row has that design and scenario's totals `eur`, without their P10 and P90 sums.\n\n**While it runs.** Every pad and formation row is listed from the first read, its counts and sums covering the wells finished so far; `partial` is true, with `Retry-After: 1` and no ETag. A done plan's answer carries an ETag; send `If-None-Match` for a 304.\n\n**Errors.** 409 for a failed plan; for a plan made with scenarios read without `scenario` (with `details.scenarios`), since its rows would add alternatives together; and, with several server tasks, for a plan running on another task until it finishes: retry shortly.",
        "parameters": [
          {
            "name": "design",
            "in": "query",
            "description": "The design whose forecasts are summed, as its index in the plan's `designs`; 400 past the last one.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9,
              "default": 0
            }
          },
          {
            "name": "scenario",
            "in": "query",
            "description": "Required on a plan made with scenarios, which answers 409 without it: the scenario whose wells are summed, named exactly as the plan's `scenarios` list it, URL-encoded (`660 ft` is `scenario=660%20ft`), and echoed.\n\nAn empty name, or one the plan doesn't have, is a 400 whose `details.scenarios` lists the plan's scenarios (empty on a plan without them, where any name is a 400). A name over 60 characters is a 400 without the list.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ip_day",
            "in": "query",
            "description": "The ip_day (days since first production) whose cumulative volumes are summed: one of GET /dataset `ip_days`, default 1080 (3 years). Another value is a 400 with `details.allowed`.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1080
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The roll-up; an ETag when done, Retry-After: 1 while running.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanRollup"
                },
                "example": {
                  "plan_id": "0b7f2c1e-5a3d-4e8f-9b6a-2d4c6e8f0a12",
                  "design": 0,
                  "scenario": null,
                  "ip_day": 1080,
                  "partial": false,
                  "units": {
                    "oil": "bbl",
                    "gas": "mcf",
                    "water": "bbl"
                  },
                  "totals": {
                    "wells": 5,
                    "wells_with_forecast": 4,
                    "wells_flagged": 2,
                    "oil": {
                      "value": 1021340.6,
                      "wells": 4
                    },
                    "gas": {
                      "value": 2250115.2,
                      "wells": 4
                    },
                    "water": {
                      "value": 1498872.9,
                      "wells": 3
                    },
                    "eur": {
                      "oil": {
                        "value": 2495001,
                        "days": 18240,
                        "wells": 4
                      },
                      "gas": {
                        "value": 4050001.3,
                        "days": 18240,
                        "wells": 3
                      },
                      "boe": {
                        "value": 2515000.8,
                        "wells": 3
                      }
                    }
                  },
                  "pads": [
                    {
                      "key": "1",
                      "name": "North pad",
                      "wells": 2,
                      "wells_with_forecast": 2,
                      "wells_flagged": 1,
                      "oil": {
                        "value": 490100.5,
                        "wells": 2
                      },
                      "gas": {
                        "value": 1100020.7,
                        "wells": 2
                      },
                      "water": {
                        "value": 998800.5,
                        "wells": 2
                      },
                      "eur": {
                        "oil": {
                          "value": 1200000.5,
                          "days": 18240,
                          "wells": 2
                        },
                        "gas": {
                          "value": 2650001,
                          "days": 18240,
                          "wells": 2
                        },
                        "boe": {
                          "value": 1641667.3,
                          "wells": 2
                        }
                      },
                      "formations": [
                        {
                          "key": "WOLFCAMP A",
                          "wells": 1,
                          "wells_with_forecast": 1,
                          "wells_flagged": 1,
                          "oil": {
                            "value": 250000.4,
                            "wells": 1
                          },
                          "gas": {
                            "value": 540000.2,
                            "wells": 1
                          },
                          "water": {
                            "value": 500100.3,
                            "wells": 1
                          },
                          "eur": {
                            "oil": {
                              "value": 610000.2,
                              "days": 18240,
                              "wells": 1
                            },
                            "gas": {
                              "value": 1300000.4,
                              "days": 18240,
                              "wells": 1
                            },
                            "boe": {
                              "value": 826666.9,
                              "wells": 1
                            }
                          }
                        },
                        {
                          "key": "WOLFCAMP B",
                          "wells": 1,
                          "wells_with_forecast": 1,
                          "wells_flagged": 0,
                          "oil": {
                            "value": 240100.1,
                            "wells": 1
                          },
                          "gas": {
                            "value": 560020.5,
                            "wells": 1
                          },
                          "water": {
                            "value": 498700.2,
                            "wells": 1
                          },
                          "eur": {
                            "oil": {
                              "value": 590000.3,
                              "days": 18240,
                              "wells": 1
                            },
                            "gas": {
                              "value": 1350000.6,
                              "days": 18240,
                              "wells": 1
                            },
                            "boe": {
                              "value": 815000.4,
                              "wells": 1
                            }
                          }
                        }
                      ]
                    },
                    {
                      "key": "2",
                      "wells": 2,
                      "wells_with_forecast": 1,
                      "wells_flagged": 1,
                      "oil": {
                        "value": 262000.3,
                        "wells": 1
                      },
                      "gas": {
                        "value": 575000.1,
                        "wells": 1
                      },
                      "water": {
                        "value": 500072.4,
                        "wells": 1
                      },
                      "eur": {
                        "oil": {
                          "value": 640000.1,
                          "days": 18240,
                          "wells": 1
                        },
                        "gas": {
                          "value": 1400000.3,
                          "days": 18240,
                          "wells": 1
                        },
                        "boe": {
                          "value": 873333.5,
                          "wells": 1
                        }
                      },
                      "formations": [
                        {
                          "key": "WOLFCAMP A",
                          "wells": 1,
                          "wells_with_forecast": 1,
                          "wells_flagged": 1,
                          "oil": {
                            "value": 262000.3,
                            "wells": 1
                          },
                          "gas": {
                            "value": 575000.1,
                            "wells": 1
                          },
                          "water": {
                            "value": 500072.4,
                            "wells": 1
                          },
                          "eur": {
                            "oil": {
                              "value": 640000.1,
                              "days": 18240,
                              "wells": 1
                            },
                            "gas": {
                              "value": 1400000.3,
                              "days": 18240,
                              "wells": 1
                            },
                            "boe": {
                              "value": 873333.5,
                              "wells": 1
                            }
                          }
                        },
                        {
                          "key": "WOLFCAMP B",
                          "wells": 1,
                          "wells_with_forecast": 0,
                          "wells_flagged": null,
                          "oil": {
                            "value": null,
                            "wells": 0
                          },
                          "gas": {
                            "value": null,
                            "wells": 0
                          },
                          "water": {
                            "value": null,
                            "wells": 0
                          },
                          "eur": {
                            "oil": {
                              "value": null,
                              "days": null,
                              "wells": 0
                            },
                            "gas": {
                              "value": null,
                              "days": null,
                              "wells": 0
                            },
                            "boe": {
                              "value": null,
                              "wells": 0
                            }
                          }
                        }
                      ]
                    },
                    {
                      "key": null,
                      "wells": 1,
                      "wells_with_forecast": 1,
                      "wells_flagged": 0,
                      "oil": {
                        "value": 269239.8,
                        "wells": 1
                      },
                      "gas": {
                        "value": 575094.4,
                        "wells": 1
                      },
                      "water": {
                        "value": null,
                        "wells": 0
                      },
                      "eur": {
                        "oil": {
                          "value": 655000.4,
                          "days": 18240,
                          "wells": 1
                        },
                        "gas": {
                          "value": null,
                          "days": null,
                          "wells": 0
                        },
                        "boe": {
                          "value": null,
                          "wells": 0
                        }
                      },
                      "formations": [
                        {
                          "key": "WOLFCAMP A",
                          "wells": 1,
                          "wells_with_forecast": 1,
                          "wells_flagged": 0,
                          "oil": {
                            "value": 269239.8,
                            "wells": 1
                          },
                          "gas": {
                            "value": 575094.4,
                            "wells": 1
                          },
                          "water": {
                            "value": null,
                            "wells": 0
                          },
                          "eur": {
                            "oil": {
                              "value": 655000.4,
                              "days": 18240,
                              "wells": 1
                            },
                            "gas": {
                              "value": null,
                              "days": null,
                              "wells": 0
                            },
                            "boe": {
                              "value": null,
                              "wells": 0
                            }
                          }
                        }
                      ]
                    }
                  ]
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/plans/{id}/curves": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        }
      ],
      "get": {
        "operationId": "getPlanCurves",
        "tags": [
          "Plans"
        ],
        "summary": "Read each well's cumulative curves to EUR",
        "description": "A done plan's wells, a page at a time, each with its cumulative volume per stream and P-level every 30 days from the first model month to its EUR. A Legacy Forecast answers too.\n\n**Curves.** `cum[m-1]` is the cumulative at day 30·m, to 0.01, as POST /exports writes it in the `monthly` table; volumes for any period are their differences, and a month without a value is null. The first `model_months` come from the model, the rest from the decline extension to the EUR, whose kind is `extension`. A curve without one ends at `model_months`, with `extension` null and `note` saying why: the plan has no EUR, water was fit without `eur_water`, a P10 or P90 on a plan made without `band_eur`, or an extension that misses its EUR.\n\nA well that couldn't be placed or has no forecast for the design, a failed stream and a missing band are each `{error}`. PlanCurvesWell lists each well's fields.\n\n**Calendar months.** With `start_date`, each curve has `calendar` (PlanCurves and PlanCurvesWell name the other fields it adds): its volume in each calendar month, C at the next month's first day minus C at this one's, to 0.01. C is 0 on and before the start date, runs straight between the `cum` points (day 30·m after the start date) and holds the last one after it. The first month runs from the start date, so it is partial unless that is a 1st; the last holds the last point, day 30·N after the start date, and when that day is a 1st it is there with volume 0.\n\n**Errors and caching.** A running or failed plan is a 409 `conflict` with `details.status`. Each page has an ETag, and `If-None-Match` answers 304.",
        "parameters": [
          {
            "name": "design",
            "in": "query",
            "description": "The design whose forecasts are read, as its index in the plan's `designs`; 400 past the last one. A Legacy Forecast has one.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "streams",
            "in": "query",
            "description": "Streams to read, comma-separated, such as `oil,gas`; default every stream the plan serves. A stream it doesn't serve is a 400 with `details.allowed`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "p_levels",
            "in": "query",
            "description": "P-levels to read, comma-separated from `P50`, `P10` and `P90`; default `P50`. Novi's P10 is the low curve. P10 or P90 on a plan without bands is a 400 with `details.allowed`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Wells on a page, 1 to 200; default 100.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Page to read: `next_cursor` from the previous page. Wells come in plan order. Any other nonempty value is a 400.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "description": "Dates each well and adds calendar months. `til`: each well's TIL date, else the plan's day (`plan_day`). A date as YYYY-MM-DD, from 1900-01-01 to 2199-12-31: that day for every well. Anything else is a 400.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of wells; an ETag on each page.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanCurves"
                },
                "example": {
                  "plan_id": "e287ce51-430c-4871-87c2-e9c4191fb412",
                  "design": 0,
                  "step_days": 30,
                  "streams": [
                    "oil",
                    "gas"
                  ],
                  "p_levels": [
                    "P50",
                    "P10"
                  ],
                  "wells": [
                    {
                      "index": 0,
                      "key": "DRAWN-0",
                      "well_uid": "54a872630fdca9a2660d598fe5467269",
                      "label": "Plan well 1",
                      "name": "Example 1H",
                      "til_date": "2027-03-01",
                      "shl": [
                        -101.93,
                        31.93
                      ],
                      "bhl": [
                        -101.93,
                        31.957
                      ],
                      "curves": {
                        "oil": {
                          "unit": "bbl",
                          "P50": {
                            "cum": [
                              18412.35,
                              33021.8,
                              45210.06,
                              702113.42
                            ],
                            "model_months": 36,
                            "extension": "arps",
                            "note": null
                          },
                          "P10": {
                            "cum": [
                              12888.65,
                              23115.26,
                              31647.04
                            ],
                            "model_months": 36,
                            "extension": null,
                            "note": "This plan was made without band_eur, so its P10 and P90 have no EUR; create it with \"band_eur\": true"
                          }
                        },
                        "gas": {
                          "error": "The forecast worker failed: gas model timed out"
                        }
                      }
                    },
                    {
                      "index": 1,
                      "key": "DRAWN-1",
                      "well_uid": "31797da6d548168574d9b653f40daf3e",
                      "label": "Plan well 2",
                      "shl": [
                        -101.928,
                        31.93
                      ],
                      "bhl": [
                        -101.928,
                        31.957
                      ],
                      "error": "No forecast: the well needs a target formation."
                    }
                  ],
                  "next_cursor": "bzoy"
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/comparisons": {
      "post": {
        "operationId": "compareForecasts",
        "tags": [
          "Plans"
        ],
        "summary": "Compare plans, scenarios or a forecast source",
        "description": "Compares two sides, each a done plan's wells under one design (`design`, 0 by default) or one scenario's (`scenario`), in one model set. Both sides may be the same plan. Nothing is stored and no model worker runs.\n\n**Sides.** A plan made with scenarios compares one scenario at a time, since its totals don't add alternatives. Each side echoes what it is and what made it (ComparisonSideEcho); a plan whose stored record can't be read echoes this server's release and the model set the request reached.\n\n**Numbers.** Every number is one GET /plans/{id} or its stats already serve: a scenario side's EUR equals that plan's totals for its scenario and design, and its cumulative at `ip_day` the summed `forecast` curve's value there (BOE: the `forecast.boe` total GET /plans/{id}?boe=true serves, over the wells with both oil and gas forecasts); its `distribution` equals GET /plans/{id}/stats' `group_by=scenario` row for it. Quantiles are of each side's wells' values (q10 the 10th-percentile well), not P-level bands. `totals` has water's EUR too when both sides fit it, and each row its unit and each side's well count.\n\n- `delta` is b − a, rounded to 0.1.\n- `delta_pct` is (b − a) / a × 100, rounded to 0.01; null when a is 0 or either value is null.\n- Swapping the sides negates every `delta` exactly, and a side compared with itself gives 0 wherever both sides have a value.\n\n**Metric and groups.** `metric`, `ip_day` and `group_by` work as ComparisonRequest describes them, and `groups` as Comparison describes it. An `eur_` metric on a side made without `eur: true` is a 400 naming the side. In a group row, a side without the key is null, and so is the row's delta. Grouping by `pad` when neither side's plan names pads is a 400 on `group_by` naming both plans, with `details.side` a: send `wells[].pad`.\n\n**Curves.** `include: [\"curves\"]` adds each side's summed curve for the metric's stream by ip_day (BOE over the wells with both oil and gas forecasts), cumulative and each step's average daily rate. With `bands` too, each side's summed P10 and P90 cumulative where its plan was made with bands (Novi's P10 is the low curve; a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan).\n\n**Warnings.** `warnings` give a code and a sentence when the sides differ in model set, in models (the same set with a changed manifest or pins), in release or in EUR settings; when one side has no EUR (the EUR rows are left out); when a side's wells lack forecasts; and when a side has no bands that `bands` asked for.\n\n**Pairing wells.** `pair` pairs the sides' wells and adds `pairs`: the method used, how many paired, and each side's unpaired wells. ComparisonPairing lists the methods.\n\n- `auto`, the default, pairs by name when every well on both sides has a real `name` (a default label such as Plan well 3 never counts) and no name repeats on a side, else by location.\n- `location` pairs each well once, the same formation first, so stacked benches pair within their bench. `name` pairs a repeated name's wells by location within it, with a `duplicate_names` warning.\n- Location pairing examines at most 64 nearby wells per well. Wells packed closer, as many on one spot, are a 400 naming `pair`: pair them by `index` or `map`.\n\n**Paired wells.** `include: [\"wells\"]` (pairing by `auto` when `pair` is absent) adds `wells`: a page of `rows`, one per pair, with each side's value, `delta` and `delta_pct`, in `wells.sort` order; and a `summary` over every pair: the count, each pair's `delta_pct` (sorted `values` under 20 pairs, else a `histogram`), its q10, q50 and q90 (quantiles of pairs, not P-levels) and `left_out`. When side a's plan has `band_eur` and the metric is an EUR, each row's `band_position` places side b's value in side a's P10 to P90 EUR, counted in `summary.band`; otherwise a `no_band_position` warning.\n\n**Changed inputs.** `include: [\"inputs\"]` adds `inputs.changed`: each input that differs on any pair (ComparisonInputChange lists them), how many pairs, and the typical change: b − a, the median among pairs with both values, or for formation the most common change.\n\n**Horizon.** `horizon: { \"years\": n }` (1 to 50, EUR on both sides) adds cumulative oil, gas and BOE rows, with `horizon_years`, at `ip_day` the last 30-day step within n × 365 days. Each well counts its forecast, then its EUR curve as `eur_curve=month` gives it, then past its EUR day its EUR.\n\n**Calendar curves.** `align: \"calendar\"` (with `include: [\"curves\"]`, and a well with a TIL date on each side) adds `curves.calendar`: each side's summed curve by month start, as GET /plans/{id} `totals.by_date` sums a plan's, with each step's average daily rate.\n\n**A forecast source.** Either side may be `{ \"source\": \"<id>\" }` (POST /forecast-sources) when the other is a plan; two sources are a 400.\n\n- The source is read as you: a private one is a 404 naming the side to another user, a share link's viewer or another tenant. Without a state store a source side is a 409.\n- `reserves_category` is required on a source holding more than one (a 400 lists them with their curve counts); Novi's P-levels never stand in for one.\n- Each well under it runs through its decline profile (GET /conventions?include=decline_profiles), each stream from day 0 at its curve's start date (a constants ratio at its parent stream's).\n- From those runs come each EUR, to its curve's limit or end date, the cumulatives at `ip_day` and `horizon`, the spread over its wells, and its summed curve on the plan side's ip_days.\n- A source has no bands. Its numbers are in bbl, mcf and BOE whatever the file's units.\n- A source whose wells would take more than 120,000,000 steps of decline-curve work (a day a curve steps through, or a day measured) is a 400 on the side naming its wells and curves: save the wells you need as a smaller source.\n- `align: \"calendar\"` runs to the first month start on or after its last stream start plus 1,080 days, each well held at its last cumulative. It needs a start date on every well (a Novi arps.csv has none: a 400) and at most 1,200 month starts (a 400 names the earliest and latest start).\n\n**Pairing a source.** On a source side:\n\n- `auto` uses the pairs saved on the source when it links to this plan, else `name` when that pairs a well, else `uwi`. `saved` uses only the saved pairs (a 400 when there are none).\n- `name` matches a source Well ID to a plan well's real name, trimmed and ignoring case; `uwi` does the same without dashes, spaces and dots. `map` takes Well IDs on the source side.\n- `location`, `index`, `tolerance_ft`, `group_by`, `normalize_lateral_ft` and `include: [\"inputs\"]` are 400s: a source has no locations, order, designs, formations, scenarios, pads, laterals or inputs.\n- Its unpaired wells and rows name Well IDs (`a_well_id`, `b_well_id`); `band_position` applies with the plan as side a.\n\n**Source warnings.** `gas_basis_differs` (a sales-gas source), `conventions_differ` (any profile but novi's), `horizons_differ` (the EURs end at different days) and `source_unpaired`.\n\n**Value.** `include: [\"value\"]` prices each side as POST /economics prices one scenario, under one deck and conventions (`deck_id`, `deck` and `conventions`, each a 400 without it), and adds `value` with the difference.\n\n- A plan side prices its wells under its design as a plan reference does: its `economics` and `breakeven` equal POST /economics with `scenarios: [{\"plan\": {id, design, scenario}}]` and `include: [\"breakeven\"]`.\n- A plan side needs a plan made with `eur: true` (a 400 naming the side); more than 50 wells are priced as one pad.\n- A forecast source side prices only its wells that pair with a plan well (by `auto` when `pair` is absent): the plan well's lateral and completions under the plan side's design, with the source well's own cumulatives on the plan side's ip_days and its EURs, to the later EUR day (`eur_days`).\n- An unpaired source well is listed in `unpriced` with a reason. When both sides price different counts, a `value_wells_differ` warning names them.\n- A side with any priced well it can't give a cash flow (a source well without water, say) has `economics` null and a `reason` naming the first.\n- `delta` is b − a for capex, npv, irr_pct, payback_months and each breakeven price, to 0.01; null where either side has none.\n\n**Value limits.** Both sides together may hold at most 5,000 wells (a source side's under its reserves category) and 5,000,000 well-months: each well's 30-day months to its EUR day (a source well's `eur_days` may pass POST /economics' 60 years), or to its curve's last ip_day if later. Past either is a 400 on `include` naming each side's count, before anything is priced: price larger sides with POST /economics in scenarios of up to 50 wells, or compare fewer wells.\n\n**Errors.** A request whose sides are plans of two model sets is a 400 naming each side's set: compare plans of one set. A missing plan, another tenant's or one on a model set you can't use is a 404, as GET /plans/{id} answers; a running or failed plan is a 409.",
        "requestBody": {
          "required": true,
          "description": "The two sides and what to measure.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ComparisonRequest"
              },
              "example": {
                "a": {
                  "plan": "00000000-0000-4000-8000-0000000000c1",
                  "scenario": "660 ft"
                },
                "b": {
                  "plan": "00000000-0000-4000-8000-0000000000c1",
                  "scenario": "1,320 ft"
                },
                "group_by": "formation",
                "include": [
                  "curves",
                  "bands"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Both sides' echoes, totals, distribution and warnings, with groups, curves, pairs, per-well rows, changed inputs and value when asked.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Comparison"
                },
                "example": {
                  "a": {
                    "kind": "plan",
                    "plan": {
                      "id": "00000000-0000-4000-8000-0000000000c1",
                      "name": "Spacing test"
                    },
                    "scenario": "660 ft",
                    "design": {
                      "index": 0,
                      "name": "Design 1"
                    },
                    "model_set": "default",
                    "release": "1.04",
                    "run_at": "2026-11-07T00:00:00.000Z",
                    "decline": {
                      "eur_years": 50,
                      "terminal_decline": 0.06,
                      "b_min": 0.5,
                      "b_max": 2.5
                    },
                    "bands": {
                      "percentiles": [
                        10,
                        90
                      ],
                      "method": "Novi's predrill bands (split conformal)",
                      "eur": false
                    },
                    "wells": 4,
                    "wells_with_forecast": 4,
                    "unplaced": {
                      "count": 0,
                      "message": null
                    }
                  },
                  "b": {
                    "kind": "plan",
                    "plan": {
                      "id": "00000000-0000-4000-8000-0000000000c1",
                      "name": "Spacing test"
                    },
                    "scenario": "1,320 ft",
                    "design": {
                      "index": 0,
                      "name": "Design 1"
                    },
                    "model_set": "default",
                    "release": "1.04",
                    "run_at": "2026-11-07T00:00:00.000Z",
                    "decline": {
                      "eur_years": 50,
                      "terminal_decline": 0.06,
                      "b_min": 0.5,
                      "b_max": 2.5
                    },
                    "bands": {
                      "percentiles": [
                        10,
                        90
                      ],
                      "method": "Novi's predrill bands (split conformal)",
                      "eur": false
                    },
                    "wells": 2,
                    "wells_with_forecast": 2,
                    "unplaced": {
                      "count": 0,
                      "message": null
                    }
                  },
                  "totals": [
                    {
                      "metric": "eur_oil",
                      "unit": "bbl",
                      "ip_day": null,
                      "a": 3456625.1,
                      "b": 1848893.4,
                      "delta": -1607731.7,
                      "delta_pct": -46.51,
                      "a_wells": 4,
                      "b_wells": 2
                    },
                    {
                      "metric": "eur_gas",
                      "unit": "mcf",
                      "ip_day": null,
                      "a": 12445337.8,
                      "b": 6579810.4,
                      "delta": -5865527.4,
                      "delta_pct": -47.13,
                      "a_wells": 4,
                      "b_wells": 2
                    },
                    {
                      "metric": "eur_boe",
                      "unit": "BOE",
                      "ip_day": null,
                      "a": 5530848.1,
                      "b": 2945528.5,
                      "delta": -2585319.6,
                      "delta_pct": -46.74,
                      "a_wells": 4,
                      "b_wells": 2
                    }
                  ],
                  "distribution": {
                    "metric": "eur_boe",
                    "unit": "BOE",
                    "ip_day": null,
                    "a": {
                      "wells": 4,
                      "missing": 0,
                      "min": 1342607.7,
                      "max": 1422304.7,
                      "mean": 1382712,
                      "quantiles": {
                        "q10": 1350777.1,
                        "q50": 1382967.9,
                        "q90": 1414442.3
                      }
                    },
                    "b": {
                      "wells": 2,
                      "missing": 0,
                      "min": 1459604.5,
                      "max": 1485924,
                      "mean": 1472764.3,
                      "quantiles": {
                        "q10": 1462236.5,
                        "q50": 1472764.3,
                        "q90": 1483292.1
                      }
                    },
                    "delta": {
                      "mean": 90052.3,
                      "q50": 89796.4
                    },
                    "delta_pct": {
                      "mean": 6.51,
                      "q50": 6.49
                    }
                  },
                  "group_by": "formation",
                  "groups": [
                    {
                      "key": "WOLFCAMP A",
                      "a": {
                        "wells": 2,
                        "missing": 0,
                        "min": 1369839,
                        "max": 1396096.7,
                        "mean": 1382967.9,
                        "quantiles": {
                          "q10": 1372464.8,
                          "q50": 1382967.9,
                          "q90": 1393470.9
                        }
                      },
                      "b": {
                        "wells": 2,
                        "missing": 0,
                        "min": 1459604.5,
                        "max": 1485924,
                        "mean": 1472764.3,
                        "quantiles": {
                          "q10": 1462236.5,
                          "q50": 1472764.3,
                          "q90": 1483292.1
                        }
                      },
                      "delta": {
                        "mean": 89796.4,
                        "q50": 89796.4
                      },
                      "delta_pct": {
                        "mean": 6.49,
                        "q50": 6.49
                      }
                    },
                    {
                      "key": "WOLFCAMP B",
                      "a": {
                        "wells": 2,
                        "missing": 0,
                        "min": 1342607.7,
                        "max": 1422304.7,
                        "mean": 1382456.2,
                        "quantiles": {
                          "q10": 1350577.4,
                          "q50": 1382456.2,
                          "q90": 1414335
                        }
                      },
                      "b": null,
                      "delta": null,
                      "delta_pct": null
                    }
                  ],
                  "curves": {
                    "axis": "ip_days",
                    "stream": "boe",
                    "unit": "BOE",
                    "rate_unit": "BOE/d",
                    "a": {
                      "ip_days": [
                        30,
                        60,
                        90
                      ],
                      "cum": [
                        96292.1,
                        205217,
                        304061.3
                      ],
                      "rate": [
                        3209.74,
                        3630.83,
                        3294.81
                      ],
                      "bands": {
                        "p10": [
                          67404.6,
                          143651.7,
                          212842.9
                        ],
                        "p90": [
                          134809.1,
                          287303.7,
                          425686
                        ]
                      }
                    },
                    "b": {
                      "ip_days": [
                        30,
                        60,
                        90
                      ],
                      "cum": [
                        50788.7,
                        108256.1,
                        160418.2
                      ],
                      "rate": [
                        1692.96,
                        1915.58,
                        1738.74
                      ],
                      "bands": {
                        "p10": [
                          35552.2,
                          75779.2,
                          112292.7
                        ],
                        "p90": [
                          71104.2,
                          151558.5,
                          224585.5
                        ]
                      }
                    }
                  },
                  "warnings": []
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/plans/{id}/pdp-wells": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        }
      ],
      "get": {
        "operationId": "listPlanPdpWells",
        "tags": [
          "Plans"
        ],
        "summary": "List the PDP wells near a plan or pad",
        "description": "Existing wells near a done plan's wells, parallel to them and producing by the plan's first TIL date, nearest first, by the gun barrel's PDP selection rule, so every client compares a plan with the same wells.\n\n**The rule.** `scope` echoes it, with each figure's rounding (PdpScope). A well's lateral runs from its heel, else its surface hole, to its bottom hole.\n\n- Scope: the plan wells in `wells` (a pad's, say), else every plan well.\n- Circle: centered on the mean of the scope wells' lateral midpoints, its radius the farthest of them plus 0.5 mi (`margin_mi`), at most GET /wells' 100 mi.\n- Candidates: the wells GET /wells `near` finds in that circle, each at its lateral midpoint, that have a lateral.\n- Kept: a candidate whose lateral runs within 15° (`parallel_deg`) of the section line, either way along it, and that first produced on or before `til_date`, the scope wells' earliest TIL date; a well without a first production date isn't kept.\n- A scope well with no TIL date at any layer comes online on the plan's creation day (UTC), as `by_date` places it.\n- The section line runs at `azimuth_deg`, else the scope wells' mean heel-to-toe direction to 0.1°, through `center`, else their mean midpoint, as POST /gun-barrels takes and gives `line`.\n\n**Results.** `matched` counts every well that passed (after the section cut, with `along`); `wells` holds the nearest `limit` (ties by wellbore key), whose keys go straight to POST /wells/production, with `lateral_length_ft` to normalise production per 1,000 ft. No drawing limit applies: not the gun barrel's 1,000 nearest candidates, its well cap or its TVD filter. `include=left_out` adds `left_out`: under `til_date` the wells that passed every other cut but first produced after `til_date` or never, and under `limit` those past `limit`.\n\n**A pad.** Send the pad's azimuth and center as `azimuth_deg` and `center`: the gun barrel draws a pad on its own line, so a pad laid at an azimuth off the 0.1° grid can keep a different set on the wells' line.\n\n**Section cut.** `along=section` keeps only the wells whose lateral overlaps the scope wells' heel-to-toe range on the section line (`along_range_ft`), each end placed as POST /gun-barrels' `heel_along_ft` and `toe_along_ft`.\n\n**Lateral reach.** With `reach=laterals`, the candidates are the wells with any part of their lateral (at GET /wells' 5-decimal ends) within `margin_mi` of any scope well's lateral, so a long-lateral pad finds the offsets beside its ends that the circle misses. The parallel, TIL, `along` and `limit` rules stay, and the list runs nearest by `distance_ft` (ties by wellbore key). Scope wells whose laterals span wider or taller than the circle's diameter plus two 50,000 ft laterals and `margin_mi` (as across the antimeridian) are a 400 naming `wells`.\n\n**A line across.** With `cross`, a line A-B drawn across the laterals, a candidate is kept, as the web's Section A-B keeps it, when its lateral (at GET /wells' 5-decimal ends) crosses A-B within half A-B of its midpoint, with its ends on either side (one may lie on it), runs within `parallel_deg` of the section line, square to A-B, and first produced on or before `til_date`. The candidates are the wells GET /wells `near` the mean of A and B finds within half A-B plus 25,000 ft, a superset of the web's search, and `distance_ft` is from that mean. `til_date` is still the scope wells': send the plan wells the line crosses as `wells` to date it by them.\n\n**Caching.** The answer carries an `ETag`; send it as `If-None-Match` for a 304.\n\n**Errors.**\n\n- 400 naming `wells`: a scope whose radius would pass 100 mi; send fewer, closer wells.\n- 400 naming the other parameter: `cross` beside `azimuth_deg`, `center`, `along` or `reach`.\n- 400 naming `cross`: A and B under 1 ft apart, or a radius past 100 mi.\n- 409: a running or failed plan, as GET /plans/{id}/wells/{index} answers.",
        "parameters": [
          {
            "name": "wells",
            "in": "query",
            "description": "Plan well indexes to measure from, comma-separated, as a pad's wells: up to 500, in any order, a repeat counted once. Absent: every well of the plan. An index past the plan's last is a 400 naming wells.",
            "schema": {
              "type": "string"
            },
            "example": "0,1"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "The most wells to return, nearest first: 1 to 50, POST /wells/production's limit. `matched` still counts them all.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 50
            }
          },
          {
            "name": "azimuth_deg",
            "in": "query",
            "description": "The section line's azimuth, to measure parallel against and, with `along=section`, to cut along: degrees clockwise from north, as POST /gun-barrels takes `line.azimuth_deg` (-360 to 360, brought into [0, 360); any number, as 164.96 or 1e-7). Send a pad's azimuth, with its `center`, when `wells` is a pad. Absent: the scope wells' mean heel-to-toe direction to 0.1°.",
            "schema": {
              "type": "number",
              "minimum": -360,
              "maximum": 360
            },
            "example": 164.96
          },
          {
            "name": "center",
            "in": "query",
            "description": "The section line's center, `lng,lat` in WGS 84 degrees, as POST /gun-barrels takes `line.center`: with `along=section`, the heel-to-toe range and each lateral's ends are measured along the line from it. Send a pad's center, with its `azimuth_deg`, when `wells` is a pad. It moves no candidate: the radius is measured from the wells' mean midpoint. Absent: that mean, to 1e-7°.",
            "schema": {
              "type": "string"
            },
            "example": "-101.95,31.95"
          },
          {
            "name": "along",
            "in": "query",
            "description": "`section`: keep only wells whose lateral overlaps the scope wells' heel-to-toe range along the section line, as the gun barrel draws its section; `scope` then names that range in `along_range_ft`. Absent: no such cut, and no `along` fields.",
            "schema": {
              "type": "string",
              "enum": [
                "section"
              ]
            }
          },
          {
            "name": "reach",
            "in": "query",
            "description": "`laterals`: candidates are the wells with any part of their lateral within `margin_mi` of any scope well's lateral, not those with a midpoint in the circle; nearest lateral first, `distance_ft` the gap to it, and `scope.reach` echoes it. Absent: the circle.",
            "schema": {
              "type": "string",
              "enum": [
                "laterals"
              ]
            }
          },
          {
            "name": "cross",
            "in": "query",
            "description": "A line A-B drawn across the laterals: `lngA,latA,lngB,latB`, four numbers in WGS 84 degrees, A then B, as `-101.91,31.9,-101.89,31.9`.\n\nKeeps the wells whose laterals cross A-B and run within `parallel_deg` of square to A-B, producing by `til_date`, as the web's Section A-B picks them. `cross` sets the section line and the candidates, so `azimuth_deg`, `center`, `along` or `reach` beside it is a 400. Absent: the scope wells' circle.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include",
            "in": "query",
            "description": "`left_out`: adds `left_out`, how many wells the TIL date and `limit` leave out. Any other value is a 400 with details.field include. Absent: no `left_out`.",
            "schema": {
              "type": "string",
              "enum": [
                "left_out"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The scope and the PDP wells.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanPdpWells"
                },
                "examples": {
                  "pad": {
                    "summary": "wells=0,1&limit=3",
                    "value": {
                      "scope": {
                        "indexes": [
                          0,
                          1
                        ],
                        "center": [
                          -102.2967109,
                          32.12053
                        ],
                        "radius_mi": 0.58,
                        "azimuth_deg": 179.2,
                        "til_date": "2027-02-01",
                        "margin_mi": 0.5,
                        "parallel_deg": 15
                      },
                      "matched": 16,
                      "wells": [
                        {
                          "wellbore_key": "SB003-01274",
                          "well_name": "YANCEY 26-38 6WD",
                          "operator": "Sample Operator C",
                          "formation": "WOLFCAMP D",
                          "first_prod": "2017-10-09",
                          "lateral_length_ft": 7450,
                          "distance_ft": 139
                        },
                        {
                          "wellbore_key": "SB003-01053",
                          "well_name": "YANCEY 26-38 5WA",
                          "operator": "Sample Operator C",
                          "formation": "WOLFCAMP A",
                          "first_prod": "2014-04-21",
                          "lateral_length_ft": 7390,
                          "distance_ft": 942
                        },
                        {
                          "wellbore_key": "SB003-01242",
                          "well_name": "YANCEY 26-38 5WD",
                          "operator": "Sample Operator C",
                          "formation": "WOLFCAMP D",
                          "first_prod": "2017-10-07",
                          "lateral_length_ft": 7450,
                          "distance_ft": 1003
                        }
                      ]
                    }
                  },
                  "section": {
                    "summary": "along=section&limit=3",
                    "value": {
                      "scope": {
                        "indexes": [
                          0,
                          1,
                          2
                        ],
                        "center": [
                          -102.285163,
                          32.12053
                        ],
                        "radius_mi": 1.26,
                        "azimuth_deg": 179.2,
                        "til_date": "2027-03-01",
                        "margin_mi": 0.5,
                        "parallel_deg": 15,
                        "along": "section",
                        "along_range_ft": [
                          -3777,
                          3777
                        ]
                      },
                      "matched": 27,
                      "wells": [
                        {
                          "wellbore_key": "SB003-01808",
                          "well_name": "VALENTINE EAST 32-44 3MS",
                          "operator": "Sample Operator C",
                          "formation": "MIDDLE SPRABERRY",
                          "first_prod": "2021-03-30",
                          "lateral_length_ft": 10080,
                          "distance_ft": 1202
                        },
                        {
                          "wellbore_key": "SB003-01522",
                          "well_name": "VALENTINE EAST 32-44 5WB",
                          "operator": "Sample Operator C",
                          "formation": "WOLFCAMP B",
                          "first_prod": "2019-07-06",
                          "lateral_length_ft": 10020,
                          "distance_ft": 1288
                        },
                        {
                          "wellbore_key": "SB003-01613",
                          "well_name": "VALENTINE EAST 32-44 4LS",
                          "operator": "Sample Operator C",
                          "formation": "LOWER SPRABERRY SHALE",
                          "first_prod": "2019-07-06",
                          "lateral_length_ft": 10000,
                          "distance_ft": 1318
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/pdp-wells": {
      "post": {
        "operationId": "listPdpWells",
        "tags": [
          "Wells"
        ],
        "summary": "List the PDP wells near drawn wells",
        "description": "GET /plans/{id}/pdp-wells for drawn wells that aren't in a plan yet, such as a gun barrel's drawn pad before a plan runs: existing wells near them, parallel to them and producing by their first TIL date, nearest first, by the same rule.\n\n**The body.** `wells` as POST /gun-barrels takes them (drawn, as POST /forecasts takes them, without `fluid_bbl_per_ft`, `proppant_lb_per_ft`, `decline` or `name`), up to 500, and the GET's options: `azimuth_deg`, `center`, `along`, `limit`, `reach`, `cross` and `include`. `cross` is two points, `[[lngA, latA], [lngB, latB]]`; the sent wells only date the wells it picks, and a point out of range is a 400 naming `cross[0]` or `cross[1]`. `include: [\"left_out\"]` is the GET's `include=left_out`.\n\n**The rule.** The rule, `scope` and every field are GET /plans/{id}/pdp-wells' (its description has them in full), with the sent wells as the scope. A well's TIL date is its own `til_date`, else today (UTC), as POST /forecasts places an undated well. There is no request-wide date, so send one date on every well; `scope.til_date` is the earliest. `scope.indexes` are the wells' positions in `wells`, 0 to n-1.\n\nA done plan's wells sent in plan order, each with its `shl`, `heel`, `bhl` and TIL date, answer the same body as GET /plans/{id}/pdp-wells on that plan when those dates are on or after the dataset's `as_of`.\n\n**Errors.** A TIL date before the dataset's `as_of` is a 400. Wells spread past GET /wells' 100 mi radius are a 400 naming `wells`: send fewer, closer wells, as one pad's.",
        "requestBody": {
          "required": true,
          "description": "Up to 500 drawn wells, each with an optional til_date, and the options.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PdpWellsRequest"
              },
              "example": {
                "wells": [
                  {
                    "shl": [
                      -101.98292,
                      32.008551
                    ],
                    "bhl": [
                      -101.98293,
                      32.029199
                    ],
                    "formation": "WOLFCAMP B",
                    "til_date": "2027-03-01"
                  },
                  {
                    "shl": [
                      -101.980782,
                      32.008551
                    ],
                    "bhl": [
                      -101.980792,
                      32.029199
                    ],
                    "formation": "WOLFCAMP B",
                    "til_date": "2027-02-01"
                  }
                ],
                "limit": 3
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The scope and the PDP wells.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanPdpWells"
                },
                "example": {
                  "scope": {
                    "indexes": [
                      0,
                      1
                    ],
                    "center": [
                      -101.981856,
                      32.018875
                    ],
                    "radius_mi": 0.56,
                    "azimuth_deg": 0,
                    "til_date": "2027-02-01",
                    "margin_mi": 0.5,
                    "parallel_deg": 15
                  },
                  "matched": 12,
                  "wells": [
                    {
                      "wellbore_key": "SB329-01534",
                      "well_name": "EDMONDSON RANCH 13-25 2WA",
                      "operator": "Sample Operator A",
                      "formation": "WOLFCAMP A",
                      "first_prod": "2015-06-27",
                      "lateral_length_ft": 7480,
                      "distance_ft": 109
                    },
                    {
                      "wellbore_key": "SB329-01452",
                      "well_name": "EDMONDSON RANCH 13-25 4WB",
                      "operator": "Sample Operator A",
                      "formation": "WOLFCAMP B",
                      "first_prod": "2015-06-25",
                      "lateral_length_ft": 7500,
                      "distance_ft": 290
                    },
                    {
                      "wellbore_key": "SB329-01393",
                      "well_name": "EDMONDSON RANCH 13-25 3WB",
                      "operator": "Sample Operator A",
                      "formation": "WOLFCAMP B",
                      "first_prod": "2015-06-26",
                      "lateral_length_ft": 7500,
                      "distance_ft": 307
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/plans/{id}/wells/{index}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        },
        {
          "name": "index",
          "in": "path",
          "required": true,
          "description": "The well's position in the plan, from 0.",
          "schema": {
            "type": "integer",
            "minimum": 0
          },
          "example": 1
        }
      ],
      "get": {
        "operationId": "getPlanWell",
        "tags": [
          "Plans"
        ],
        "summary": "Get one plan well",
        "description": "A done plan's well in full, shaped like a POST /forecasts well: its summary, spacing neighbors (other plan wells by their DRAWN key and label), spacing features at ip_day 1 and subsurface values.\n\n**Options.** `eur_curve` adds the curve of each oil and gas EUR, `boe=true` each forecast's BOE, and `include=scored_inputs` the inputs each design scored, by feature name.\n\n**Caching.** The answer carries an `ETag`; send it as `If-None-Match` for a 304.",
        "parameters": [
          {
            "name": "eur_curve",
            "in": "query",
            "description": "Add each oil and gas EUR's curve (and water's with `eur_water`), `eur.curve`, on a plan made with `eur: true` (400 otherwise): cumulative volumes to the EUR's `days`.\n\nIt continues the forecast from its last ip_day on the same decline fit: `month` every 30 days (the export's monthly cumulatives), `year` every 360 days plus the EUR's day. A decline-curve extension, not a model output.",
            "schema": {
              "type": "string",
              "enum": [
                "month",
                "year"
              ]
            }
          },
          {
            "name": "boe",
            "in": "query",
            "description": "`true` adds `boe` beside `oil`, `gas` and `water` in every forecast that has streams, computed when read, so older plans have it too. Absent, empty or `false`: no `boe` key anywhere.\n\nBOE is oil plus gas / 6 (6 mcf per bbl), on ip_days where both have a value; on a set serving one of them the other counts 0, and serving neither, BOE is 0.\n\nIts P10 adds oil's P10 and gas's P10 / 6 (P90 likewise). The models predict each stream apart, so this isn't the P10 of BOE itself; it is as wide as BOE's would be if oil and gas moved together. Novi's P10 is the low case. Totals add the BOE of the wells that have both oil and gas forecasts, and say how many in `wells`. With eur_curve, BOE's EUR has its curve too. Anything else is a 400.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include",
            "in": "query",
            "description": "`decline_base` adds `inputs.resolved.decline.base` when the well has `resolved.decline`, and nothing otherwise; older plans leave it out. `scored_inputs` adds `scored_inputs`, the inputs each design scored, by feature name. Names may be comma-separated or repeated, each once. Unknown or duplicate names are 400.",
            "schema": {
              "type": "string",
              "enum": [
                "decline_base",
                "scored_inputs",
                "decline_base,scored_inputs",
                "scored_inputs,decline_base"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The plan well.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForecastWell"
                },
                "examples": {
                  "well": {
                    "summary": "A plan well",
                    "value": {
                      "index": 1,
                      "key": "DRAWN-1",
                      "label": "Plan well 2",
                      "inputs": {
                        "shl": [
                          -101.927,
                          31.93
                        ],
                        "bhl": [
                          -101.927,
                          31.957
                        ],
                        "formation": "WOLFCAMP A",
                        "tvd_ft": 9150,
                        "landing_below_top_ft": null
                      },
                      "lateral_length_ft": 9823,
                      "estimates": {
                        "tvd_ft": 9150,
                        "tvd_source": "input"
                      },
                      "forecasts": [
                        {
                          "design": 0,
                          "oil": {
                            "model_num": "M20260930-sample-O-d1",
                            "target": "novi_oil",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              197555.5,
                              293697.4,
                              358047.1
                            ],
                            "missing": [],
                            "eur": {
                              "value": 843377.57891,
                              "days": 18240,
                              "arps": {
                                "q_i": 1035.260001,
                                "d": 0.005623,
                                "b": 1.041667,
                                "terminal_year": 15.047338
                              }
                            }
                          },
                          "gas": {
                            "model_num": "M20260930-sample-G-d1",
                            "target": "novi_gas",
                            "unit": "mcf",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              376011.9,
                              626928.9,
                              824453
                            ],
                            "missing": [],
                            "eur": {
                              "value": 3165004.763032,
                              "days": 18240,
                              "arps": {
                                "q_i": 1535.540193,
                                "d": 0.003444,
                                "b": 1.819444,
                                "terminal_year": 8.445411
                              }
                            }
                          },
                          "water": {
                            "model_num": "M20260930-sample-W-d1",
                            "target": "novi_water",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              397166.8,
                              567162.1,
                              684973.2
                            ],
                            "missing": []
                          },
                          "checks": {
                            "available": true,
                            "model_num": "M20260930-sample-O-d1",
                            "flagged": false,
                            "out_of_range": [],
                            "missing": [],
                            "unknown_formation": null
                          }
                        },
                        {
                          "design": 1,
                          "oil": {
                            "model_num": "M20260930-sample-O-d1",
                            "target": "novi_oil",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              206468.5,
                              306948.1,
                              374201.1
                            ],
                            "missing": [],
                            "eur": {
                              "value": 881434.358253,
                              "days": 18240,
                              "arps": {
                                "q_i": 1081.98089,
                                "d": 0.005623,
                                "b": 1.041667,
                                "terminal_year": 15.047338
                              }
                            }
                          },
                          "gas": {
                            "model_num": "M20260930-sample-G-d1",
                            "target": "novi_gas",
                            "unit": "mcf",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              392976.4,
                              655214,
                              861649.7
                            ],
                            "missing": [],
                            "eur": {
                              "value": 3307789.678989,
                              "days": 18240,
                              "arps": {
                                "q_i": 1604.812299,
                                "d": 0.003444,
                                "b": 1.819444,
                                "terminal_year": 8.445411
                              }
                            }
                          },
                          "water": {
                            "model_num": "M20260930-sample-W-d1",
                            "target": "novi_water",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              418662.3,
                              596328.4,
                              719454.8
                            ],
                            "missing": []
                          },
                          "checks": {
                            "available": true,
                            "model_num": "M20260930-sample-O-d1",
                            "flagged": false,
                            "out_of_range": [],
                            "missing": [],
                            "unknown_formation": null
                          }
                        }
                      ],
                      "spacing": {
                        "node": {
                          "azimuth": 0.820832,
                          "heel": [
                            -101.927,
                            31.93
                          ],
                          "heel_is_virtual": false,
                          "pad_wells": 0
                        },
                        "neighbors": [
                          {
                            "neighbor": "SB329-10803",
                            "well_name": "WILLINGHAM WEST 36-48 3WB",
                            "operator": "Sample Operator A",
                            "formation": "WOLFCAMP B",
                            "first_prod": "2025-09-11",
                            "heel_lon": -101.926707,
                            "heel_lat": 31.936083,
                            "bhl_lon": -101.926472,
                            "bhl_lat": 31.963345,
                            "position": "stagger",
                            "cone": "rightstaggerbelow",
                            "category": "parent",
                            "signedxy": 118.849578,
                            "signedtvd": 538,
                            "minxy": 118.849578,
                            "mintvd": 538,
                            "mintangent": 550.971163,
                            "overlap": 0.774705,
                            "edge_date": "2026-10-17",
                            "daysonline": 401,
                            "impact_factor": 0.041462,
                            "prior_oil": 284394
                          },
                          {
                            "neighbor": "DRAWN-0",
                            "well_name": "Plan well 1",
                            "formation": "WOLFCAMP A",
                            "heel_lon": -101.93,
                            "heel_lat": 31.93,
                            "bhl_lon": -101.93,
                            "bhl_lat": 31.957,
                            "position": "lateral",
                            "cone": "leftlateral",
                            "category": "nonparent",
                            "signedxy": -930.634175,
                            "signedtvd": -39,
                            "minxy": 930.634175,
                            "mintvd": 39,
                            "mintangent": 931.451001,
                            "overlap": 0.999999,
                            "edge_date": "2026-10-17",
                            "daysonline": 0,
                            "impact_factor": 0.12793,
                            "prior_oil": 0
                          }
                        ]
                      },
                      "features": {
                        "novi_ip_day": 1,
                        "novi_depletion": null,
                        "novi_net_depletion": null,
                        "novi_spacing_is_child": true,
                        "novi_spacing_parent_count": 4,
                        "novi_spacing_nonparent_count": 3,
                        "novi_spacing_parent_in_formation": "PARENT IN OTHER FORMATION",
                        "novi_spacing_wells_in_radius": 7,
                        "novi_spacing_boundedness_score": 4,
                        "novi_spacing_minxy": 118.849578,
                        "novi_spacing_drainage_area": 1154649.680823,
                        "novi_spacing_lateralcloser_id": "DRAWN-0",
                        "novi_spacing_lateralcloser_mintangent": 931.451001,
                        "novi_unique_key": "DRAWN-1"
                      },
                      "subsurface": {
                        "novi_bvi_avg": 0.051954,
                        "novi_bvi_avg_wolfcamp_a": 0.051954,
                        "novi_bvi_ofnet": 0.059706,
                        "novi_bvi_ofnet_wolfcamp_a": 0.059706,
                        "novi_min_grid_dist": 0,
                        "novi_structuraldepth": -8908.107326,
                        "novi_structuraldepth_wolfcamp_a": -8908.107326,
                        "novi_thickness_avg": 432.705067,
                        "novi_thickness_avg_wolfcamp_a": 432.705067,
                        "novi_thickness_ofnet": 312.995095,
                        "novi_thickness_ofnet_wolfcamp_a": 312.995095
                      }
                    }
                  },
                  "eurCurve": {
                    "summary": "eur_curve=year, each curve cut to its first three and last points",
                    "value": {
                      "index": 1,
                      "key": "DRAWN-1",
                      "label": "Plan well 2",
                      "inputs": {
                        "shl": [
                          -101.927,
                          31.93
                        ],
                        "bhl": [
                          -101.927,
                          31.957
                        ],
                        "formation": "WOLFCAMP A",
                        "tvd_ft": 9150,
                        "landing_below_top_ft": null
                      },
                      "lateral_length_ft": 9823,
                      "estimates": {
                        "tvd_ft": 9150,
                        "tvd_source": "input"
                      },
                      "forecasts": [
                        {
                          "design": 0,
                          "oil": {
                            "model_num": "M20260930-sample-O-d1",
                            "target": "novi_oil",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              197429.8,
                              293525.6,
                              357850.9
                            ],
                            "missing": [],
                            "eur": {
                              "value": 843003.732322,
                              "days": 18240,
                              "arps": {
                                "q_i": 1034.881063,
                                "d": 0.005623,
                                "b": 1.041667,
                                "terminal_year": 15.047338
                              },
                              "curve": {
                                "step_days": 360,
                                "ip_days": [
                                  1440,
                                  1800,
                                  2160,
                                  18240
                                ],
                                "values": [
                                  406493.07,
                                  445635.7,
                                  478433.95,
                                  843003.73
                                ]
                              }
                            }
                          },
                          "gas": {
                            "model_num": "M20260930-sample-G-d1",
                            "target": "novi_gas",
                            "unit": "mcf",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              375774.4,
                              626571.6,
                              824021
                            ],
                            "missing": [],
                            "eur": {
                              "value": 3163747.490145,
                              "days": 18240,
                              "arps": {
                                "q_i": 1534.998765,
                                "d": 0.003444,
                                "b": 1.819444,
                                "terminal_year": 8.445411
                              },
                              "curve": {
                                "step_days": 360,
                                "ip_days": [
                                  1440,
                                  1800,
                                  2160,
                                  18240
                                ],
                                "values": [
                                  990646.94,
                                  1137685.02,
                                  1270503.66,
                                  3163747.49
                                ]
                              }
                            }
                          },
                          "water": {
                            "model_num": "M20260930-sample-W-d1",
                            "target": "novi_water",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              396957.3,
                              566871.2,
                              684637.6
                            ],
                            "missing": []
                          },
                          "checks": {
                            "available": true,
                            "model_num": "M20260930-sample-O-d1",
                            "flagged": false,
                            "out_of_range": [],
                            "missing": [],
                            "unknown_formation": null
                          }
                        },
                        {
                          "design": 1,
                          "oil": {
                            "model_num": "M20260930-sample-O-d1",
                            "target": "novi_oil",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              206337.2,
                              306768.5,
                              373996
                            ],
                            "missing": [],
                            "eur": {
                              "value": 881041.161865,
                              "days": 18240,
                              "arps": {
                                "q_i": 1081.579661,
                                "d": 0.005623,
                                "b": 1.041667,
                                "terminal_year": 15.047338
                              },
                              "curve": {
                                "step_days": 360,
                                "ip_days": [
                                  1440,
                                  1800,
                                  2160,
                                  18240
                                ],
                                "values": [
                                  424833.13,
                                  465742.06,
                                  500020.32,
                                  881041.16
                                ]
                              }
                            }
                          },
                          "gas": {
                            "model_num": "M20260930-sample-G-d1",
                            "target": "novi_gas",
                            "unit": "mcf",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              392728.2,
                              654840.6,
                              861198.2
                            ],
                            "missing": [],
                            "eur": {
                              "value": 3306481.763729,
                              "days": 18240,
                              "arps": {
                                "q_i": 1604.25044,
                                "d": 0.003444,
                                "b": 1.819444,
                                "terminal_year": 8.445411
                              },
                              "curve": {
                                "step_days": 360,
                                "ip_days": [
                                  1440,
                                  1800,
                                  2160,
                                  18240
                                ],
                                "values": [
                                  1035341.49,
                                  1189013.22,
                                  1327823.99,
                                  3306481.76
                                ]
                              }
                            }
                          },
                          "water": {
                            "model_num": "M20260930-sample-W-d1",
                            "target": "novi_water",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              418443.5,
                              596024.5,
                              719104.2
                            ],
                            "missing": []
                          },
                          "checks": {
                            "available": true,
                            "model_num": "M20260930-sample-O-d1",
                            "flagged": false,
                            "out_of_range": [],
                            "missing": [],
                            "unknown_formation": null
                          }
                        }
                      ],
                      "spacing": {
                        "node": {
                          "azimuth": 0.820832,
                          "heel": [
                            -101.927,
                            31.93
                          ],
                          "heel_is_virtual": false,
                          "pad_wells": 0
                        },
                        "neighbors": [
                          {
                            "neighbor": "SB329-10803",
                            "well_name": "WILLINGHAM WEST 36-48 3WB",
                            "operator": "Sample Operator A",
                            "formation": "WOLFCAMP B",
                            "first_prod": "2025-09-11",
                            "heel_lon": -101.926707,
                            "heel_lat": 31.936083,
                            "bhl_lon": -101.926472,
                            "bhl_lat": 31.963345,
                            "position": "stagger",
                            "cone": "rightstaggerbelow",
                            "category": "parent",
                            "signedxy": 118.849578,
                            "signedtvd": 538,
                            "minxy": 118.849578,
                            "mintvd": 538,
                            "mintangent": 550.971163,
                            "overlap": 0.774705,
                            "edge_date": "2026-10-21",
                            "daysonline": 405,
                            "impact_factor": 0.041462,
                            "prior_oil": 284394
                          },
                          {
                            "neighbor": "DRAWN-0",
                            "well_name": "Plan well 1",
                            "formation": "WOLFCAMP A",
                            "heel_lon": -101.93,
                            "heel_lat": 31.93,
                            "bhl_lon": -101.93,
                            "bhl_lat": 31.957,
                            "position": "lateral",
                            "cone": "leftlateral",
                            "category": "nonparent",
                            "signedxy": -930.634175,
                            "signedtvd": -39,
                            "minxy": 930.634175,
                            "mintvd": 39,
                            "mintangent": 931.451001,
                            "overlap": 0.999999,
                            "edge_date": "2026-10-21",
                            "daysonline": 0,
                            "impact_factor": 0.12793,
                            "prior_oil": 0
                          }
                        ]
                      },
                      "features": {
                        "novi_ip_day": 1,
                        "novi_depletion": null,
                        "novi_net_depletion": null,
                        "novi_spacing_is_child": true,
                        "novi_spacing_parent_count": 4,
                        "novi_spacing_nonparent_count": 3,
                        "novi_spacing_parent_in_formation": "PARENT IN OTHER FORMATION",
                        "novi_spacing_wells_in_radius": 7,
                        "novi_spacing_boundedness_score": 4,
                        "novi_spacing_minxy": 118.849578,
                        "novi_spacing_drainage_area": 1154649.680823,
                        "novi_spacing_lateralcloser_id": "DRAWN-0",
                        "novi_spacing_lateralcloser_mintangent": 931.451001,
                        "novi_unique_key": "DRAWN-1"
                      },
                      "subsurface": {
                        "novi_bvi_avg": 0.051954,
                        "novi_bvi_avg_wolfcamp_a": 0.051954,
                        "novi_bvi_ofnet": 0.059706,
                        "novi_bvi_ofnet_wolfcamp_a": 0.059706,
                        "novi_min_grid_dist": 0,
                        "novi_structuraldepth": -8908.107326,
                        "novi_structuraldepth_wolfcamp_a": -8908.107326,
                        "novi_thickness_avg": 432.705067,
                        "novi_thickness_avg_wolfcamp_a": 432.705067,
                        "novi_thickness_ofnet": 312.995095,
                        "novi_thickness_ofnet_wolfcamp_a": 312.995095
                      }
                    }
                  },
                  "scoredInputs": {
                    "summary": "include=scored_inputs, each design's values cut to a few inputs",
                    "value": {
                      "index": 1,
                      "key": "DRAWN-1",
                      "label": "Plan well 2",
                      "inputs": {
                        "shl": [
                          -101.927,
                          31.93
                        ],
                        "bhl": [
                          -101.927,
                          31.957
                        ],
                        "formation": "WOLFCAMP A",
                        "tvd_ft": 9150,
                        "landing_below_top_ft": null
                      },
                      "lateral_length_ft": 9823,
                      "estimates": {
                        "tvd_ft": 9150,
                        "tvd_source": "input"
                      },
                      "forecasts": [
                        {
                          "design": 0,
                          "oil": {
                            "model_num": "M20260930-sample-O-d1",
                            "target": "novi_oil",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              197555.5,
                              293697.4,
                              358047.1
                            ],
                            "missing": [],
                            "eur": {
                              "value": 843377.57891,
                              "days": 18240,
                              "arps": {
                                "q_i": 1035.260001,
                                "d": 0.005623,
                                "b": 1.041667,
                                "terminal_year": 15.047338
                              }
                            }
                          },
                          "gas": {
                            "model_num": "M20260930-sample-G-d1",
                            "target": "novi_gas",
                            "unit": "mcf",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              376011.9,
                              626928.9,
                              824453
                            ],
                            "missing": [],
                            "eur": {
                              "value": 3165004.763032,
                              "days": 18240,
                              "arps": {
                                "q_i": 1535.540193,
                                "d": 0.003444,
                                "b": 1.819444,
                                "terminal_year": 8.445411
                              }
                            }
                          },
                          "water": {
                            "model_num": "M20260930-sample-W-d1",
                            "target": "novi_water",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              397166.8,
                              567162.1,
                              684973.2
                            ],
                            "missing": []
                          },
                          "checks": {
                            "available": true,
                            "model_num": "M20260930-sample-O-d1",
                            "flagged": false,
                            "out_of_range": [],
                            "missing": [],
                            "unknown_formation": null
                          }
                        },
                        {
                          "design": 1,
                          "oil": {
                            "model_num": "M20260930-sample-O-d1",
                            "target": "novi_oil",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              206468.5,
                              306948.1,
                              374201.1
                            ],
                            "missing": [],
                            "eur": {
                              "value": 881434.358253,
                              "days": 18240,
                              "arps": {
                                "q_i": 1081.98089,
                                "d": 0.005623,
                                "b": 1.041667,
                                "terminal_year": 15.047338
                              }
                            }
                          },
                          "gas": {
                            "model_num": "M20260930-sample-G-d1",
                            "target": "novi_gas",
                            "unit": "mcf",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              392976.4,
                              655214,
                              861649.7
                            ],
                            "missing": [],
                            "eur": {
                              "value": 3307789.678989,
                              "days": 18240,
                              "arps": {
                                "q_i": 1604.812299,
                                "d": 0.003444,
                                "b": 1.819444,
                                "terminal_year": 8.445411
                              }
                            }
                          },
                          "water": {
                            "model_num": "M20260930-sample-W-d1",
                            "target": "novi_water",
                            "unit": "bbl",
                            "ip_days": [
                              360,
                              720,
                              1080
                            ],
                            "values": [
                              418662.3,
                              596328.4,
                              719454.8
                            ],
                            "missing": []
                          },
                          "checks": {
                            "available": true,
                            "model_num": "M20260930-sample-O-d1",
                            "flagged": false,
                            "out_of_range": [],
                            "missing": [],
                            "unknown_formation": null
                          }
                        }
                      ],
                      "spacing": {
                        "node": {
                          "azimuth": 0.820832,
                          "heel": [
                            -101.927,
                            31.93
                          ],
                          "heel_is_virtual": false,
                          "pad_wells": 0
                        },
                        "neighbors": [
                          {
                            "neighbor": "SB329-10803",
                            "well_name": "WILLINGHAM WEST 36-48 3WB",
                            "operator": "Sample Operator A",
                            "formation": "WOLFCAMP B",
                            "first_prod": "2025-09-11",
                            "heel_lon": -101.926707,
                            "heel_lat": 31.936083,
                            "bhl_lon": -101.926472,
                            "bhl_lat": 31.963345,
                            "position": "stagger",
                            "cone": "rightstaggerbelow",
                            "category": "parent",
                            "signedxy": 118.849578,
                            "signedtvd": 538,
                            "minxy": 118.849578,
                            "mintvd": 538,
                            "mintangent": 550.971163,
                            "overlap": 0.774705,
                            "edge_date": "2026-10-17",
                            "daysonline": 401,
                            "impact_factor": 0.041462,
                            "prior_oil": 284394
                          },
                          {
                            "neighbor": "DRAWN-0",
                            "well_name": "Plan well 1",
                            "formation": "WOLFCAMP A",
                            "heel_lon": -101.93,
                            "heel_lat": 31.93,
                            "bhl_lon": -101.93,
                            "bhl_lat": 31.957,
                            "position": "lateral",
                            "cone": "leftlateral",
                            "category": "nonparent",
                            "signedxy": -930.634175,
                            "signedtvd": -39,
                            "minxy": 930.634175,
                            "mintvd": 39,
                            "mintangent": 931.451001,
                            "overlap": 0.999999,
                            "edge_date": "2026-10-17",
                            "daysonline": 0,
                            "impact_factor": 0.12793,
                            "prior_oil": 0
                          }
                        ]
                      },
                      "features": {
                        "novi_ip_day": 1,
                        "novi_depletion": null,
                        "novi_net_depletion": null,
                        "novi_spacing_is_child": true,
                        "novi_spacing_parent_count": 4,
                        "novi_spacing_nonparent_count": 3,
                        "novi_spacing_parent_in_formation": "PARENT IN OTHER FORMATION",
                        "novi_spacing_wells_in_radius": 7,
                        "novi_spacing_boundedness_score": 4,
                        "novi_spacing_minxy": 118.849578,
                        "novi_spacing_drainage_area": 1154649.680823,
                        "novi_spacing_lateralcloser_id": "DRAWN-0",
                        "novi_spacing_lateralcloser_mintangent": 931.451001,
                        "novi_unique_key": "DRAWN-1"
                      },
                      "subsurface": {
                        "novi_bvi_avg": 0.051954,
                        "novi_bvi_avg_wolfcamp_a": 0.051954,
                        "novi_bvi_ofnet": 0.059706,
                        "novi_bvi_ofnet_wolfcamp_a": 0.059706,
                        "novi_min_grid_dist": 0,
                        "novi_structuraldepth": -8908.107326,
                        "novi_structuraldepth_wolfcamp_a": -8908.107326,
                        "novi_thickness_avg": 432.705067,
                        "novi_thickness_avg_wolfcamp_a": 432.705067,
                        "novi_thickness_ofnet": 312.995095,
                        "novi_thickness_ofnet_wolfcamp_a": 312.995095
                      },
                      "scored_inputs": [
                        {
                          "design": 0,
                          "ip_day": 30,
                          "values": {
                            "novi_lateral_length": 9822.562897,
                            "novi_tvd": 9150,
                            "novi_calc_fluid_per_length": 54.5,
                            "novi_calc_proppant_per_length": 2709.5,
                            "novi_formation": "WOLFCAMP A",
                            "novi_spacing_parent_daysonline": 448
                          }
                        },
                        {
                          "design": 1,
                          "ip_day": 30,
                          "values": {
                            "novi_lateral_length": 9822.562897,
                            "novi_tvd": 9150,
                            "novi_calc_fluid_per_length": 60,
                            "novi_calc_proppant_per_length": 3000,
                            "novi_formation": "WOLFCAMP A",
                            "novi_spacing_parent_daysonline": 448
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/plans/{id}/wells/{index}/explanations/{design}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        },
        {
          "name": "index",
          "in": "path",
          "required": true,
          "description": "The well's position in the plan, from 0.",
          "schema": {
            "type": "integer",
            "minimum": 0
          },
          "example": 1
        },
        {
          "name": "design",
          "in": "path",
          "required": true,
          "description": "The design's position in the plan's `designs`, from 0.",
          "schema": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9
          },
          "example": 0
        }
      ],
      "get": {
        "operationId": "explainPlanWell",
        "tags": [
          "Plans"
        ],
        "summary": "Explain a plan well",
        "parameters": [
          {
            "name": "top",
            "in": "query",
            "description": "How many features per SHAP row and contributing wells to keep, 1 to 50.\n\nIt keeps the largest features (by absolute contribution) and heaviest wells. Default: all features, 25 wells.\n\nThe features cut are summed into one `(other)` entry (never a feature name; left out when nothing is cut), and the wells cut add to `other_weight`. A row's contributions still sum to the uncut row's (null contributions are left out), and the response keeps its shape with fewer entries; with residual, each row's `forecast` and `residual` are the uncut row's.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            },
            "example": 5
          },
          {
            "name": "ip_day",
            "in": "query",
            "description": "Only this ip_day's SHAP row in each stream, for \"why at 1 year\" without every day: one of the ip_days in the explanation's `shap` rows, which are GET /dataset `ip_days`. Without it, every ip_day.\n\nAnother value is a 400 with them in `details.allowed`; a value that isn't digits is refused before the explanation is computed. With `top`, the row is picked first and then cut. `contributing_wells` and `other_weight` are one list per stream, not per ip_day, so they are the same with or without it. A design with no forecast to explain has no rows, so any ip_day is a 400 there: ask without it to read why.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "compare",
            "in": "query",
            "description": "The references to compare with, comma-separated: `formation`, `dataset`, `analogs`.\n\nEach explained stream gains `comparisons`, one per reference.\n\n`formation` is the wells the model explained in this well's formation (a typical Wolfcamp A well, say), `dataset` every well it explained. At each ip_day, `values` holds, by feature, this well's SHAP contribution minus the reference wells' mean: read an entry as \"compared with a typical Wolfcamp A well, this input adds (or removes) N\". It rearranges the same SHAP values, so it can't contradict them.\n\n- `value` is the reference wells' mean `expected_value` plus their mean contributions (`start_from` `reference`), or this well's own `expected_value` plus theirs where no mean is stored (`start_from` `well`).\n- `(baseline)` in `values` is this well's `expected_value` less the reference mean: mostly its lateral length against theirs, in models that scale by lateral. It comes only with `start_from` `reference`, not when it rounds to 0, and never counts toward `top` or `(other)`.\n- `value` plus `values` is this well's `expected_value` plus its SHAP values (each rounded to 0.001); the SHAP row's `residual` is what they leave out of the forecast.\n- `wells` counts the reference at that ip_day (long ip_days rest on older wells); under 5, `value` is null, `values` empty and `start_from` absent.\n- `top` folds small differences into `(other)`; `ip_day` keeps one row. A reference without a baseline (a formation the model never saw) is `{reference, error}`; GET /models/{model_num}/baselines lists them.\n\n`analogs`, on model sets that store their analogs' SHAP, averages this forecast's own first 15 analogs per stream the same way (a missing feature counts 0), in the analogs list's ranking (reweighed by `analog_weights` when sent), whether or not `analogs` is asked; `analogs` itself comes only when asked. Its `keys` name them, nearest first. It is `{reference, error}` when the dataset has no analog index, the set stores no analog SHAP or it can't be read (tried again after a minute), the analogs can't be ranked, or the model has no training analogs of this forecast in its formation.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "spread",
            "in": "query",
            "description": "`true` adds `analog_spread` to each explained stream.\n\nAn analog spread, not the model's uncertainty: for the model's own P10/P90, send `bands: true`.\n\nIt is the 10th, 50th and 90th percentiles (q10 the low end) of what the model's 50 heaviest contributing training wells actually produced by each ip_day, each scaled to this well's lateral length (wells without one are left out). Only wells whose production reached the ip_day count (`wells`); under 5, the quantiles are null. `contributing_wells` still lists 25, or `top` when that is fewer, and `other_weight` is re-summed from 50 weights, so it can differ in the last digit.\n\n`forecast` says whether the served forecast (as GET /plans/{id}/wells/{index} serves it; on POST /forecasts, `forecasts[d]` before `ip_days` cuts it) is below, within or above q10 to q90, compared before rounding; null without quantiles or a served value. `driver` names the input that moves it there.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "analogs",
            "in": "query",
            "description": "`true` adds `analogs` to each explained stream, from the explanation the plan keeps (no new model call).\n\nThe model's own analog wells for this forecast, from its training wells, each stream from its own model.\n\nThey are the 50 nearest wells of the same formation and parent/child status whose lateral is within 25% of this well's (widened to 50%, then 100%, until 5 pass), by distance over the model's inputs at its last ip_day, standard-scored and weighted by mean |SHAP| (`weights`). `wells` lists them nearest first, whatever `top`.\n\n`spread` is the 10th, 50th and 90th percentiles of what they produced by ip_day, scaled to this well's lateral, as `analog_spread`: an analog spread, not the model's uncertainty. Unless `coverage` passes, it is `{error}` with the measured figure (the wells are still listed): on the model's held-out wells, q10 to q90 must have held 70% to 90% of actual production at `coverage.ip_day` (nominal 80%) over at least 300 wells. `coverage.measured` is always given.\n\nTheir type curve: POST /wells/typecurve with their keys as `wells`, `normalize_lateral_ft` = `spread.lateral_length_ft` and `quantiles: [10, 50, 90]` matches `spread` while that lateral is within 100 to 20,000 ft.\n\nA dataset without an analog index (the default dataset), or a set before its index is installed, answers `analogs: {error}` with the reason; `analog_spread` is unchanged.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "inputs",
            "in": "query",
            "description": "`true` adds `inputs` to each SHAP row: the value of each feature its `values` lists (not `(other)`), as the model read it in that ip_day's model row, so a driver reads with its input (\"proppant 2,800 lb/ft adds X bbl\"). Goes with `ip_day` and `top`; with `format=csv` it changes nothing.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "residual",
            "in": "query",
            "description": "`true` adds `forecast` and `residual` to each SHAP row; show the residual beside the drivers (\"not attributed\") so the parts add up to the forecast.\n\n`forecast` is the forecast served at that ip_day for this design, as GET /plans/{id}/wells/{index} serves it (on POST /forecasts, `forecasts[d]` before `ip_days` cuts it), or null. `residual` = `forecast` − `expected_value` − the sum of `values`, unrounded, on the uncut row, so `top` and `ip_day` don't change it; null when either is null. On a causal model set (GET /model-sets?include=model_type) SHAP values approximate the treatment effect, so the residual can be large. With `format=csv` it changes nothing.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "driver",
            "in": "query",
            "description": "`true` (400 without `spread=true` or `analogs=true`) adds `driver` to every analog spread row: the model input that moves this forecast furthest the way the row's `forecast` flag points.\n\nIt is `{feature, value, reference}`: with `below`, the most negative contribution; with `above`, the most positive; in the stream's unit to 0.001, from the uncut SHAP row. With `reference` `formation`, a contribution is this well's SHAP value minus the typical well's of its formation at that ip_day (the `compare=formation` baseline, when it has at least 5 wells there; a missing feature counts 0); otherwise `model`, the raw SHAP value. Null when the flag is `within` or null, or no input moves it that way (a contribution rounding to 0 counts as none). `comparisons` still come only with `compare`.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "weight_counts",
            "in": "query",
            "description": "`true` adds `weighted_wells` and `effective_wells` to each explained stream: how many training wells carry weight, and how concentrated it is.\n\nThey count every training well, not only those `contributing_wells` lists: check them before saying a forecast rests on the listed wells. Both are null, with `weights_error`, for a fit without tree weights or counts; all-zero weights give `weighted_wells` 0 and `effective_wells` null. With `format=csv` it changes nothing.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "analogs_detail",
            "in": "query",
            "description": "`true` (400 without `analogs=true`) adds each analog's production, EURs and model inputs to `analogs.wells`.\n\n- `cum_oil_360`, `cum_oil_720`, `cum_oil_1080`, `cum_gas_360`, `cum_gas_720`, `cum_gas_1080`: actual cumulative oil and gas (bbl, mcf) at 1, 2 and 3 years of 30-day months, unscaled; null where it hasn't produced that long. `cum_oil_life`, `cum_gas_life`: to date.\n- `eur_oil`, `eur_gas`: EUR (bbl, mcf) from Novi's type-curve decline fit, as `eur: true` runs it, on its actual cumulative at every 30-day ip_day (its last 400), unscaled.\n- `inputs`: the model's raw inputs for it at the distance's ip_day (`basis`), in `weights` order, null where missing.\n\nAn EUR is null when the fit fails, without production at every 30-day ip_day from 30 to 360, with a history longer than `eur_years`, or below the cumulative to date. One not above its last 30-day cumulative is a flat extension, kept only for an analog without production in its last 90 days (Novi's dry-well rule). An EUR from under 3 years of production (a null `cum_oil_1080` or `cum_gas_1080`) is less certain.\n\n`analogs.inputs` gives this forecast's own inputs the same way. `analogs.eur` gives the `basis`, the `decline` settings and how many got each EUR (`fitted`); it is `{error}` when the server has no EUR or the fit failed or took over 30 s. The settings are each well's own once a layer below the plan reaches any well with a setting other than `water`; else the plan's (made with `eur: true`), the forecast's `decline`, or GET /dataset `eur.defaults`.\n\nEach analog is fit once per request; the worker keeps recent fits, so a repeat is cheaper. Nothing else in the answer changes.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "format",
            "in": "query",
            "description": "`csv` (with `analogs=true`, else 400) downloads the analogs as a CSV table instead of the JSON explanation; `json` is the default.\n\nThe file is `text/csv`, an attachment named `plan-well-<n>-design-<m>-analogs-<YYYY-MM-DD>.csv` (positions from 1, the server's UTC day; `analogs-weighted` with `analog_weights`), without an ETag.\n\nPer stream with analogs, oil, gas then water: a row for this well (`rank` 0, `well_name` \"This well\", its formation, lateral, inputs and `eur_basis`: `analogs.eur.basis` or its error), then one per analog, nearest first (`rank` 1 to 50). A stream whose analogs or explanation is `{error}` adds no rows (the JSON answer says why), so the table can be its header alone.\n\nColumns: `stream`, `rank`, `key`, `distance`, `well_name`, `operator`, `formation`, `first_prod`, `lateral_length`, `heel_lon`, `heel_lat`, `bhl_lon`, `bhl_lat`, the cumulatives and EURs of `analogs_detail`, `eur_basis` (with `analog_weights`, then `analogs_basis` on rank 0 rows), then each model input by highest weight, then name; blank where a model lacks it. An input header that would repeat another gets `input_` in front until unique. Text starting with `=`, `+`, `-`, `@`, a tab or a carriage return gets a leading `'`, so a spreadsheet doesn't run it.\n\n`ip_day`, `top`, `compare` and `spread` are checked but don't change the table.",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ],
              "default": "json"
            }
          },
          {
            "name": "analog_weights",
            "in": "query",
            "description": "Comma-separated `feature:weight` pairs, as `novi_lateral_length:0.4,novi_tvd:0`, sent once (400 without `analogs=true` or when repeated); send a `+` (as in `1e+2`) as `%2B`, since a bare `+` in a query is a space.\n\nYour weights for the analog distance, as shares on the scale of `analogs.weights[].weight`, one map for every stream's model. A named input takes exactly its share and the model's other inputs split the rest as the model weighs them; when nothing takes the rest, the shares sent are rescaled to sum to 1. A model with none of the names answers as without them.\n\nWeights are finite, from 0 (which drops an input), summing to 1 at most. A 400: a name no model in the set takes (`details.allowed` lists their inputs), a malformed pair, a repeated name, a negative or non-finite weight, or a sum over 1. Weights that all come to 0, or weighted inputs that don't vary across the candidates, answer `analogs: {error}`.\n\nA reweighted stream gives `analogs.analog_weights` (yours), `weights` (the distance's, heaviest first, each with its `model_weight`) and `basis`, naming the inputs you weighted; `method` stays `shap_weighted`. Its `spread` is `{error}` unless it lists the wells the model's weights list, since `coverage` (still given) was measured with those. The filters don't change; `analogs_detail` and `format=csv` follow the reweighted analogs. Without an analog index, names aren't checked.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "description": "Why a done plan's well forecasts what it does under one design, from the model rows the plan kept: per stream, SHAP per ip_day and the top 25 training wells by tree weight, with their header details.\n\n**SHAP.** `expected_value`, the model's average, plus `values` by feature approximates the forecast, exactly only where the model's SHAP is additive. Formation's one-hot columns are summed into one.\n\n**Options.** `top` and `ip_day` cut the answer; `compare`, `spread`, `analogs` (with `analogs_detail` and `analog_weights`), `inputs`, `residual`, `driver` and `weight_counts` add to it, each as its parameter says; `format=csv` downloads the analogs as a table. `spread` comes from a new explanation each time, not the one the plan keeps.\n\n**Computing and caching.** The explanation is computed on the first request, its streams in parallel, and kept with the plan. A forecast worker answers one request at a time, so that request waits behind a running plan. The answer carries an `ETag`; send it as `If-None-Match` for a 304.",
        "responses": {
          "200": {
            "description": "The explanation; with format=csv, the analogs table.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "Content-Disposition": {
                "$ref": "#/components/headers/AnalogsContentDisposition"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanWellExplanation"
                },
                "examples": {
                  "all": {
                    "summary": "Every ip_day (trimmed)",
                    "value": {
                      "index": 1,
                      "label": "Plan well 2",
                      "design": 1,
                      "oil": {
                        "model_num": "M20260930-sample-O-d1",
                        "unit": "bbl",
                        "shap": [
                          {
                            "ip_day": 360,
                            "expected_value": 241814.903,
                            "values": {
                              "novi_spacing_lateralcloser_mintangent": -19161.635,
                              "novi_spacing_parent_daysonline": -18169.57,
                              "novi_spacing_staggercloser_mintangent": -16477.119,
                              "novi_calc_proppant_per_length": 16457.388,
                              "novi_spacing_parent_mintangent": -14886.891
                            }
                          },
                          {
                            "ip_day": 720,
                            "expected_value": 369542.508,
                            "values": {
                              "novi_spacing_parent_daysonline": -30675.353,
                              "novi_spacing_lateralcloser_mintangent": -30575.169,
                              "novi_spacing_staggercloser_mintangent": -26232.534,
                              "novi_spacing_parent_mintangent": -25089.688,
                              "novi_calc_proppant_per_length": 24896.199
                            }
                          },
                          {
                            "ip_day": 1080,
                            "expected_value": 457603.702,
                            "values": {
                              "novi_spacing_parent_daysonline": -40080.828,
                              "novi_spacing_lateralcloser_mintangent": -38670.782,
                              "novi_spacing_staggercloser_mintangent": -33136.684,
                              "novi_spacing_parent_mintangent": -32754.42,
                              "novi_calc_proppant_per_length": 30656.137
                            }
                          }
                        ],
                        "other_weight": 0.317147,
                        "contributing_wells": [
                          {
                            "key": "SB329-05507",
                            "weight": 0.050625,
                            "well_name": "ASHBY EAST 20-32 5WA",
                            "operator": "Sample Operator B",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2020-09-18",
                            "heel_lon": -102.114399,
                            "heel_lat": 31.921589,
                            "bhl_lon": -102.114347,
                            "bhl_lat": 31.949186
                          },
                          {
                            "key": "SB317-01868",
                            "weight": 0.049106,
                            "well_name": "VICKERY TRUST 20-32 4WA",
                            "operator": "Sample Operator D",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2017-03-03",
                            "heel_lon": -102.007688,
                            "heel_lat": 32.095788,
                            "bhl_lon": -102.00741,
                            "bhl_lat": 32.123217
                          }
                        ]
                      },
                      "gas": {
                        "model_num": "M20260930-sample-G-d1",
                        "unit": "mcf",
                        "shap": [
                          {
                            "ip_day": 360,
                            "expected_value": 437075.197,
                            "values": {
                              "novi_tvd": 38389.79,
                              "novi_spacing_lateralcloser_mintangent": -35936.395,
                              "novi_spacing_parent_daysonline": -34207.019,
                              "novi_spacing_staggercloser_mintangent": -30871.249,
                              "novi_calc_proppant_per_length": 30514.567
                            }
                          },
                          {
                            "ip_day": 720,
                            "expected_value": 752418.726,
                            "values": {
                              "novi_spacing_parent_daysonline": -65921.78,
                              "novi_tvd": 65178.643,
                              "novi_spacing_lateralcloser_mintangent": -64940.584,
                              "novi_spacing_staggercloser_mintangent": -55640.357,
                              "novi_spacing_parent_mintangent": -54286.037
                            }
                          },
                          {
                            "ip_day": 1080,
                            "expected_value": 1007989.356,
                            "values": {
                              "novi_spacing_parent_daysonline": -93913.267,
                              "novi_spacing_lateralcloser_mintangent": -89108.164,
                              "novi_tvd": 86630.75,
                              "novi_spacing_parent_mintangent": -77264.364,
                              "novi_spacing_staggercloser_mintangent": -76232.78
                            }
                          }
                        ],
                        "other_weight": 0.373752,
                        "contributing_wells": [
                          {
                            "key": "SB329-05507",
                            "weight": 0.046811,
                            "well_name": "ASHBY EAST 20-32 5WA",
                            "operator": "Sample Operator B",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2020-09-18",
                            "heel_lon": -102.114399,
                            "heel_lat": 31.921589,
                            "bhl_lon": -102.114347,
                            "bhl_lat": 31.949186
                          },
                          {
                            "key": "SB329-03547",
                            "weight": 0.045975,
                            "well_name": "UNDERHILL TRUST 10-22 5WA",
                            "operator": "Sample Operator A",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2019-06-28",
                            "heel_lon": -101.956996,
                            "heel_lat": 31.950614,
                            "bhl_lon": -101.957205,
                            "bhl_lat": 31.978285
                          }
                        ]
                      },
                      "water": {
                        "model_num": "M20260930-sample-W-d1",
                        "unit": "bbl",
                        "shap": [
                          {
                            "ip_day": 360,
                            "expected_value": 478622.783,
                            "values": {
                              "novi_spacing_lateralcloser_mintangent": -32879.02,
                              "novi_spacing_parent_daysonline": -31049.294,
                              "novi_spacing_staggercloser_mintangent": -28274.344,
                              "novi_calc_proppant_per_length": 28217.912,
                              "novi_spacing_parent_mintangent": -25649.033
                            }
                          },
                          {
                            "ip_day": 720,
                            "expected_value": 711755.405,
                            "values": {
                              "novi_spacing_lateralcloser_mintangent": -53394.087,
                              "novi_spacing_parent_daysonline": -53295.091,
                              "novi_spacing_staggercloser_mintangent": -45813.211,
                              "novi_spacing_parent_mintangent": -43947.711,
                              "novi_calc_proppant_per_length": 43391.489
                            }
                          },
                          {
                            "ip_day": 1080,
                            "expected_value": 878172.27,
                            "values": {
                              "novi_spacing_parent_daysonline": -70614.21,
                              "novi_spacing_lateralcloser_mintangent": -68461.313,
                              "novi_spacing_staggercloser_mintangent": -58666.752,
                              "novi_spacing_parent_mintangent": -58177.922,
                              "novi_calc_proppant_per_length": 54116.925
                            }
                          }
                        ],
                        "other_weight": 0.347319,
                        "contributing_wells": [
                          {
                            "key": "SB329-05507",
                            "weight": 0.04324,
                            "well_name": "ASHBY EAST 20-32 5WA",
                            "operator": "Sample Operator B",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2020-09-18",
                            "heel_lon": -102.114399,
                            "heel_lat": 31.921589,
                            "bhl_lon": -102.114347,
                            "bhl_lat": 31.949186
                          },
                          {
                            "key": "SB317-01868",
                            "weight": 0.042629,
                            "well_name": "VICKERY TRUST 20-32 4WA",
                            "operator": "Sample Operator D",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2017-03-03",
                            "heel_lon": -102.007688,
                            "heel_lat": 32.095788,
                            "bhl_lon": -102.00741,
                            "bhl_lat": 32.123217
                          }
                        ]
                      }
                    }
                  },
                  "ipDay": {
                    "summary": "ip_day=360 (trimmed)",
                    "value": {
                      "index": 1,
                      "label": "Plan well 2",
                      "design": 1,
                      "oil": {
                        "model_num": "M20260930-sample-O-d1",
                        "unit": "bbl",
                        "shap": [
                          {
                            "ip_day": 360,
                            "expected_value": 241814.903,
                            "values": {
                              "novi_spacing_lateralcloser_mintangent": -19161.635,
                              "novi_spacing_parent_daysonline": -18169.57,
                              "novi_spacing_staggercloser_mintangent": -16477.119,
                              "novi_calc_proppant_per_length": 16457.388,
                              "novi_spacing_parent_mintangent": -14886.891
                            }
                          }
                        ],
                        "other_weight": 0.317147,
                        "contributing_wells": [
                          {
                            "key": "SB329-05507",
                            "weight": 0.050625,
                            "well_name": "ASHBY EAST 20-32 5WA",
                            "operator": "Sample Operator B",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2020-09-18",
                            "heel_lon": -102.114399,
                            "heel_lat": 31.921589,
                            "bhl_lon": -102.114347,
                            "bhl_lat": 31.949186
                          },
                          {
                            "key": "SB317-01868",
                            "weight": 0.049106,
                            "well_name": "VICKERY TRUST 20-32 4WA",
                            "operator": "Sample Operator D",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2017-03-03",
                            "heel_lon": -102.007688,
                            "heel_lat": 32.095788,
                            "bhl_lon": -102.00741,
                            "bhl_lat": 32.123217
                          }
                        ]
                      },
                      "gas": {
                        "model_num": "M20260930-sample-G-d1",
                        "unit": "mcf",
                        "shap": [
                          {
                            "ip_day": 360,
                            "expected_value": 437075.197,
                            "values": {
                              "novi_tvd": 38389.79,
                              "novi_spacing_lateralcloser_mintangent": -35936.395,
                              "novi_spacing_parent_daysonline": -34207.019,
                              "novi_spacing_staggercloser_mintangent": -30871.249,
                              "novi_calc_proppant_per_length": 30514.567
                            }
                          }
                        ],
                        "other_weight": 0.373752,
                        "contributing_wells": [
                          {
                            "key": "SB329-05507",
                            "weight": 0.046811,
                            "well_name": "ASHBY EAST 20-32 5WA",
                            "operator": "Sample Operator B",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2020-09-18",
                            "heel_lon": -102.114399,
                            "heel_lat": 31.921589,
                            "bhl_lon": -102.114347,
                            "bhl_lat": 31.949186
                          },
                          {
                            "key": "SB329-03547",
                            "weight": 0.045975,
                            "well_name": "UNDERHILL TRUST 10-22 5WA",
                            "operator": "Sample Operator A",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2019-06-28",
                            "heel_lon": -101.956996,
                            "heel_lat": 31.950614,
                            "bhl_lon": -101.957205,
                            "bhl_lat": 31.978285
                          }
                        ]
                      },
                      "water": {
                        "model_num": "M20260930-sample-W-d1",
                        "unit": "bbl",
                        "shap": [
                          {
                            "ip_day": 360,
                            "expected_value": 478622.783,
                            "values": {
                              "novi_spacing_lateralcloser_mintangent": -32879.02,
                              "novi_spacing_parent_daysonline": -31049.294,
                              "novi_spacing_staggercloser_mintangent": -28274.344,
                              "novi_calc_proppant_per_length": 28217.912,
                              "novi_spacing_parent_mintangent": -25649.033
                            }
                          }
                        ],
                        "other_weight": 0.347319,
                        "contributing_wells": [
                          {
                            "key": "SB329-05507",
                            "weight": 0.04324,
                            "well_name": "ASHBY EAST 20-32 5WA",
                            "operator": "Sample Operator B",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2020-09-18",
                            "heel_lon": -102.114399,
                            "heel_lat": 31.921589,
                            "bhl_lon": -102.114347,
                            "bhl_lat": 31.949186
                          },
                          {
                            "key": "SB317-01868",
                            "weight": 0.042629,
                            "well_name": "VICKERY TRUST 20-32 4WA",
                            "operator": "Sample Operator D",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2017-03-03",
                            "heel_lon": -102.007688,
                            "heel_lat": 32.095788,
                            "bhl_lon": -102.00741,
                            "bhl_lat": 32.123217
                          }
                        ]
                      }
                    }
                  },
                  "compared": {
                    "summary": "compare=formation,dataset&spread=true&ip_day=360&top=5 (trimmed)",
                    "value": {
                      "index": 1,
                      "label": "Plan well 2",
                      "design": 1,
                      "oil": {
                        "model_num": "M20260930-sample-O-d1",
                        "unit": "bbl",
                        "shap": [
                          {
                            "ip_day": 360,
                            "expected_value": 241814.903,
                            "values": {
                              "novi_spacing_lateralcloser_mintangent": -19084.443,
                              "novi_spacing_parent_daysonline": -18180.47,
                              "novi_spacing_staggercloser_mintangent": -16572.743,
                              "novi_calc_proppant_per_length": 16535.566,
                              "novi_spacing_parent_mintangent": -15139.632,
                              "(other)": 16963.998
                            }
                          }
                        ],
                        "other_weight": 0.763382,
                        "contributing_wells": [
                          {
                            "key": "SB329-05507",
                            "weight": 0.050625,
                            "well_name": "ASHBY EAST 20-32 5WA",
                            "operator": "Sample Operator B",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2020-09-18",
                            "heel_lon": -102.114399,
                            "heel_lat": 31.921589,
                            "bhl_lon": -102.114347,
                            "bhl_lat": 31.949186
                          },
                          {
                            "key": "SB317-01868",
                            "weight": 0.049106,
                            "well_name": "VICKERY TRUST 20-32 4WA",
                            "operator": "Sample Operator D",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2017-03-03",
                            "heel_lon": -102.007688,
                            "heel_lat": 32.095788,
                            "bhl_lon": -102.00741,
                            "bhl_lat": 32.123217
                          }
                        ],
                        "comparisons": [
                          {
                            "reference": "formation",
                            "formation": "WOLFCAMP A",
                            "label": "Typical Wolfcamp A well",
                            "source": "mean SHAP over the WOLFCAMP A wells of a seeded sample of 60 producing wells per formation (sample data), per ip_day",
                            "rows": [
                              {
                                "ip_day": 360,
                                "wells": 53,
                                "value": 175650.75,
                                "start_from": "reference",
                                "values": {
                                  "novi_lateral_length": 36934.393,
                                  "novi_calc_proppant_per_length": 20695.177,
                                  "novi_spacing_parent_daysonline": -15557.137,
                                  "novi_spacing_parent_mintangent": -13337.499,
                                  "novi_spacing_staggercloser_mintangent": -11747.555,
                                  "(other)": 13699.05
                                }
                              }
                            ]
                          },
                          {
                            "reference": "dataset",
                            "formation": null,
                            "label": "Typical well in the dataset",
                            "source": "mean SHAP over a seeded sample of 60 producing wells per formation (sample data), per ip_day",
                            "rows": [
                              {
                                "ip_day": 360,
                                "wells": 421,
                                "value": 135190.854,
                                "start_from": "reference",
                                "values": {
                                  "novi_formation": 34223.99,
                                  "novi_lateral_length": 27724.846,
                                  "novi_bvi_avg": 25061.433,
                                  "novi_calc_proppant_per_length": 19530.387,
                                  "novi_spacing_parent_daysonline": -14603.769,
                                  "(other)": -20790.562
                                }
                              }
                            ]
                          }
                        ],
                        "analog_spread": {
                          "basis": "actual cumulative production of the forecast's 50 heaviest contributing training wells, each scaled to this well's 9,850 ft lateral",
                          "lateral_length_ft": 9823,
                          "wells_considered": 50,
                          "min_wells": 5,
                          "rows": [
                            {
                              "ip_day": 360,
                              "wells": 41,
                              "q10": 159964.2,
                              "q50": 222281.3,
                              "q90": 321541.2,
                              "forecast": "within"
                            }
                          ]
                        }
                      },
                      "gas": {
                        "model_num": "M20260930-sample-G-d1",
                        "unit": "mcf",
                        "shap": [
                          {
                            "ip_day": 360,
                            "expected_value": 437075.197,
                            "values": {
                              "novi_tvd": 38781.932,
                              "novi_spacing_lateralcloser_mintangent": -35795.539,
                              "novi_spacing_parent_daysonline": -34428.315,
                              "novi_spacing_staggercloser_mintangent": -31084.898,
                              "novi_calc_proppant_per_length": 30697.916,
                              "(other)": -12518.124
                            }
                          }
                        ],
                        "other_weight": 0.783601,
                        "contributing_wells": [
                          {
                            "key": "SB329-05507",
                            "weight": 0.046811,
                            "well_name": "ASHBY EAST 20-32 5WA",
                            "operator": "Sample Operator B",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2020-09-18",
                            "heel_lon": -102.114399,
                            "heel_lat": 31.921589,
                            "bhl_lon": -102.114347,
                            "bhl_lat": 31.949186
                          },
                          {
                            "key": "SB329-03547",
                            "weight": 0.045975,
                            "well_name": "UNDERHILL TRUST 10-22 5WA",
                            "operator": "Sample Operator A",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2019-06-28",
                            "heel_lon": -101.956996,
                            "heel_lat": 31.950614,
                            "bhl_lon": -101.957205,
                            "bhl_lat": 31.978285
                          }
                        ],
                        "comparisons": [
                          {
                            "reference": "formation",
                            "formation": "WOLFCAMP A",
                            "label": "Typical Wolfcamp A well",
                            "source": "mean SHAP over the WOLFCAMP A wells of a seeded sample of 60 producing wells per formation (sample data), per ip_day",
                            "rows": [
                              {
                                "ip_day": 360,
                                "wells": 53,
                                "value": 331992.596,
                                "start_from": "reference",
                                "values": {
                                  "novi_lateral_length": 68731.19,
                                  "novi_calc_proppant_per_length": 38369.172,
                                  "novi_spacing_parent_daysonline": -29462.31,
                                  "novi_spacing_parent_mintangent": -25600.455,
                                  "novi_spacing_staggercloser_mintangent": -22160.209,
                                  "(other)": 30858.185
                                }
                              }
                            ]
                          },
                          {
                            "reference": "dataset",
                            "formation": null,
                            "label": "Typical well in the dataset",
                            "source": "mean SHAP over a seeded sample of 60 producing wells per formation (sample data), per ip_day",
                            "rows": [
                              {
                                "ip_day": 360,
                                "wells": 421,
                                "value": 279522.288,
                                "start_from": "reference",
                                "values": {
                                  "novi_formation": 55043.978,
                                  "novi_lateral_length": 53164.104,
                                  "novi_calc_proppant_per_length": 36410.088,
                                  "novi_bvi_avg": 29361.989,
                                  "novi_spacing_parent_daysonline": -27714.054,
                                  "(other)": -33060.224
                                }
                              }
                            ]
                          }
                        ],
                        "analog_spread": {
                          "basis": "actual cumulative production of the forecast's 50 heaviest contributing training wells, each scaled to this well's 9,850 ft lateral",
                          "lateral_length_ft": 9823,
                          "wells_considered": 50,
                          "min_wells": 5,
                          "rows": [
                            {
                              "ip_day": 360,
                              "wells": 43,
                              "q10": 320422.1,
                              "q50": 430138.9,
                              "q90": 617620.4,
                              "forecast": "within"
                            }
                          ]
                        }
                      },
                      "water": {
                        "model_num": "M20260930-sample-W-d1",
                        "unit": "bbl",
                        "shap": [
                          {
                            "ip_day": 360,
                            "expected_value": 478622.783,
                            "values": {
                              "novi_spacing_lateralcloser_mintangent": -32755.114,
                              "novi_spacing_parent_daysonline": -31121.93,
                              "novi_spacing_staggercloser_mintangent": -28426.661,
                              "novi_calc_proppant_per_length": 28330.753,
                              "novi_spacing_parent_mintangent": -26092.045,
                              "(other)": 29885.716
                            }
                          }
                        ],
                        "other_weight": 0.794722,
                        "contributing_wells": [
                          {
                            "key": "SB329-05507",
                            "weight": 0.04324,
                            "well_name": "ASHBY EAST 20-32 5WA",
                            "operator": "Sample Operator B",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2020-09-18",
                            "heel_lon": -102.114399,
                            "heel_lat": 31.921589,
                            "bhl_lon": -102.114347,
                            "bhl_lat": 31.949186
                          },
                          {
                            "key": "SB317-01868",
                            "weight": 0.042629,
                            "well_name": "VICKERY TRUST 20-32 4WA",
                            "operator": "Sample Operator D",
                            "formation": "WOLFCAMP A",
                            "first_prod": "2017-03-03",
                            "heel_lon": -102.007688,
                            "heel_lat": 32.095788,
                            "bhl_lon": -102.00741,
                            "bhl_lat": 32.123217
                          }
                        ],
                        "comparisons": [
                          {
                            "reference": "formation",
                            "formation": "WOLFCAMP A",
                            "label": "Typical Wolfcamp A well",
                            "source": "mean SHAP over the WOLFCAMP A wells of a seeded sample of 60 producing wells per formation (sample data), per ip_day",
                            "rows": [
                              {
                                "ip_day": 360,
                                "wells": 53,
                                "value": 348496.375,
                                "start_from": "reference",
                                "values": {
                                  "novi_lateral_length": 73945.812,
                                  "novi_calc_proppant_per_length": 35584.296,
                                  "novi_calc_fluid_per_length": 26658.77,
                                  "novi_spacing_parent_daysonline": -26561.934,
                                  "novi_spacing_parent_mintangent": -22955.389,
                                  "(other)": -16724.428
                                }
                              }
                            ]
                          },
                          {
                            "reference": "dataset",
                            "formation": null,
                            "label": "Typical well in the dataset",
                            "source": "mean SHAP over a seeded sample of 60 producing wells per formation (sample data), per ip_day",
                            "rows": [
                              {
                                "ip_day": 360,
                                "wells": 421,
                                "value": 301557.077,
                                "start_from": "reference",
                                "values": {
                                  "novi_lateral_length": 58576.9,
                                  "novi_formation": 46465.476,
                                  "novi_calc_proppant_per_length": 33680.425,
                                  "novi_spacing_parent_daysonline": -24449.289,
                                  "novi_calc_fluid_per_length": 24326.258,
                                  "(other)": -21713.345
                                }
                              }
                            ]
                          }
                        ],
                        "analog_spread": {
                          "basis": "actual cumulative production of the forecast's 50 heaviest contributing training wells, each scaled to this well's 9,850 ft lateral",
                          "lateral_length_ft": 9823,
                          "wells_considered": 50,
                          "min_wells": 5,
                          "rows": [
                            {
                              "ip_day": 360,
                              "wells": 40,
                              "q10": 330633.5,
                              "q50": 462957.5,
                              "q90": 643981.6,
                              "forecast": "within"
                            }
                          ]
                        }
                      }
                    }
                  },
                  "analogs": {
                    "summary": "analogs=true&ip_day=810&top=2 on a fit without tree weights (trimmed to 2 of 50 wells and the top weights; water as a model outside the gate answers)",
                    "value": {
                      "index": 1,
                      "label": "Plan well 2",
                      "design": 0,
                      "oil": {
                        "model_num": "M20261022-sampleb-O-d1",
                        "unit": "bbl",
                        "shap": [
                          {
                            "ip_day": 810,
                            "expected_value": 394172.887,
                            "values": {
                              "novi_lateral_length": -76548.211,
                              "novi_spacing_lateralcloser_mintangent": -49916.987,
                              "(other)": -80753.726
                            }
                          }
                        ],
                        "other_weight": 1,
                        "contributing_wells": [],
                        "analogs": {
                          "method": "shap_weighted",
                          "note": "Analog spread, not the model's uncertainty",
                          "basis": "the 50 training wells nearest this forecast in the model's inputs at ip_day 1,080, by distance over standard scores weighted by the model's mean |SHAP|, of the 76 in the same formation, also children, with a lateral within 25% of this well's",
                          "formation": "WOLFCAMP A",
                          "child": true,
                          "lateral_band_pct": 25,
                          "candidates": 76,
                          "weights": [
                            {
                              "feature": "novi_lateral_length",
                              "weight": 0.4279
                            },
                            {
                              "feature": "novi_bvi_avg",
                              "weight": 0.1391
                            },
                            {
                              "feature": "novi_spacing_lateralcloser_mintangent",
                              "weight": 0.1083
                            }
                          ],
                          "wells": [
                            {
                              "key": "SB173-01377",
                              "distance": 0.5567,
                              "well_name": "GOODNIGHT EAST 11-12 2WA",
                              "operator": "Sample Operator E",
                              "formation": "WOLFCAMP A",
                              "first_prod": "2020-07-07",
                              "lateral_length": 7410,
                              "heel_lon": -101.65625960511859,
                              "heel_lat": 31.739776092705878,
                              "bhl_lon": -101.680196,
                              "bhl_lat": 31.739703
                            },
                            {
                              "key": "SB173-01335",
                              "distance": 0.5708,
                              "well_name": "GOODNIGHT EAST 11-12 4WA",
                              "operator": "Sample Operator E",
                              "formation": "WOLFCAMP A",
                              "first_prod": "2020-07-07",
                              "lateral_length": 7310,
                              "heel_lon": -101.65613466346278,
                              "heel_lat": 31.736800255273067,
                              "bhl_lon": -101.680071,
                              "bhl_lat": 31.736727
                            }
                          ],
                          "coverage": {
                            "ip_day": 810,
                            "k": 50,
                            "nominal": 0.8,
                            "measured": 0.752,
                            "wells": 351,
                            "gate": {
                              "min": 0.7,
                              "max": 0.9,
                              "wells": 300
                            },
                            "shown": true
                          },
                          "spread": {
                            "basis": "actual cumulative production of these 50 model analogs, each scaled to this well's 7,444 ft lateral. Analog spread, not the model's uncertainty: its q10-q90 held 75.2% of 351 held-out wells' day-810 oil (nominal 80%)",
                            "lateral_length_ft": 7444,
                            "wells_considered": 50,
                            "min_wells": 5,
                            "rows": [
                              {
                                "ip_day": 810,
                                "wells": 50,
                                "q10": 153926.1,
                                "q50": 214683.6,
                                "q90": 296993.3,
                                "forecast": "within"
                              }
                            ]
                          }
                        }
                      },
                      "gas": {
                        "model_num": "M20261022-sampleb-G-d1",
                        "unit": "mcf",
                        "shap": [
                          {
                            "ip_day": 810,
                            "expected_value": 820824.266,
                            "values": {
                              "novi_lateral_length": -166336.013,
                              "novi_spacing_lateralcloser_mintangent": -110597.338,
                              "(other)": -116130.053
                            }
                          }
                        ],
                        "other_weight": 1,
                        "contributing_wells": [],
                        "analogs": {
                          "method": "shap_weighted",
                          "note": "Analog spread, not the model's uncertainty",
                          "basis": "the 50 training wells nearest this forecast in the model's inputs at ip_day 1,080, by distance over standard scores weighted by the model's mean |SHAP|, of the 76 in the same formation, also children, with a lateral within 25% of this well's",
                          "formation": "WOLFCAMP A",
                          "child": true,
                          "lateral_band_pct": 25,
                          "candidates": 76,
                          "weights": [
                            {
                              "feature": "novi_tvd",
                              "weight": 0.3412
                            },
                            {
                              "feature": "novi_lateral_length",
                              "weight": 0.3131
                            }
                          ],
                          "wells": [
                            {
                              "key": "SB317-02196",
                              "distance": 0.4703,
                              "well_name": "CASWELL 31-43 5WA",
                              "operator": "Sample Operator F",
                              "formation": "WOLFCAMP A",
                              "first_prod": "2022-01-17",
                              "lateral_length": 7320,
                              "heel_lon": -102.14497003127399,
                              "heel_lat": 32.16801502214365,
                              "bhl_lon": -102.14477,
                              "bhl_lat": 32.188338
                            }
                          ],
                          "coverage": {
                            "ip_day": 810,
                            "k": 50,
                            "nominal": 0.8,
                            "measured": 0.798,
                            "wells": 351,
                            "gate": {
                              "min": 0.7,
                              "max": 0.9,
                              "wells": 300
                            },
                            "shown": true
                          },
                          "spread": {
                            "basis": "actual cumulative production of these 50 model analogs, each scaled to this well's 7,444 ft lateral. Analog spread, not the model's uncertainty: its q10-q90 held 79.8% of 351 held-out wells' day-810 gas (nominal 80%)",
                            "lateral_length_ft": 7444,
                            "wells_considered": 50,
                            "min_wells": 5,
                            "rows": [
                              {
                                "ip_day": 810,
                                "wells": 50,
                                "q10": 350240.9,
                                "q50": 448444.6,
                                "q90": 718216,
                                "forecast": "within"
                              }
                            ]
                          }
                        }
                      },
                      "water": {
                        "model_num": "M20261022-sampleb-W-d1",
                        "unit": "bbl",
                        "shap": [
                          {
                            "ip_day": 810,
                            "expected_value": 757805.422,
                            "values": {
                              "novi_lateral_length": -149094.437,
                              "novi_spacing_lateralcloser_mintangent": -87119.186,
                              "(other)": -153100.453
                            }
                          }
                        ],
                        "other_weight": 1,
                        "contributing_wells": [],
                        "analogs": {
                          "method": "shap_weighted",
                          "note": "Analog spread, not the model's uncertainty",
                          "basis": "the 50 training wells nearest this forecast in the model's inputs at ip_day 1,080, by distance over standard scores weighted by the model's mean |SHAP|, of the 76 in the same formation, also children, with a lateral within 25% of this well's",
                          "formation": "WOLFCAMP A",
                          "child": true,
                          "lateral_band_pct": 25,
                          "candidates": 76,
                          "weights": [
                            {
                              "feature": "novi_lateral_length",
                              "weight": 0.472
                            },
                            {
                              "feature": "novi_spacing_lateralcloser_mintangent",
                              "weight": 0.1099
                            }
                          ],
                          "wells": [
                            {
                              "key": "SB317-02196",
                              "distance": 0.5595,
                              "well_name": "CASWELL 31-43 5WA",
                              "operator": "Sample Operator F",
                              "formation": "WOLFCAMP A",
                              "first_prod": "2022-01-17",
                              "lateral_length": 7320,
                              "heel_lon": -102.14497003127399,
                              "heel_lat": 32.16801502214365,
                              "bhl_lon": -102.14477,
                              "bhl_lat": 32.188338
                            }
                          ],
                          "coverage": {
                            "ip_day": 810,
                            "k": 50,
                            "nominal": 0.8,
                            "measured": 0.652,
                            "wells": 351,
                            "gate": {
                              "min": 0.7,
                              "max": 0.9,
                              "wells": 300
                            },
                            "shown": false
                          },
                          "spread": {
                            "error": "Not shown: its q10-q90 held 65.2% of 351 held-out wells' day-810 water (nominal 80%), and it must hold 70%-90% on at least 300 held-out wells"
                          }
                        }
                      }
                    }
                  },
                  "analogsDetail": {
                    "summary": "analogs=true&analogs_detail=true&ip_day=810&top=2 on a plan made without eur, so the analogs' EURs use the dataset defaults (trimmed to 1 of 50 wells per stream and the top 2 weights and inputs)",
                    "value": {
                      "index": 1,
                      "label": "Plan well 2",
                      "design": 0,
                      "oil": {
                        "model_num": "M20261022-sampleb-O-d1",
                        "unit": "bbl",
                        "shap": [
                          {
                            "ip_day": 810,
                            "expected_value": 394172.887,
                            "values": {
                              "novi_lateral_length": -99932.825,
                              "novi_bvi_avg": 30805.994,
                              "(other)": 26222.976999999995
                            }
                          }
                        ],
                        "other_weight": 1,
                        "contributing_wells": [],
                        "analogs": {
                          "method": "shap_weighted",
                          "note": "Analog spread, not the model's uncertainty",
                          "basis": "the 50 training wells nearest this forecast in the model's inputs at ip_day 1,080, by distance over standard scores weighted by the model's mean |SHAP|, of the 76 in the same formation, also parents, with a lateral within 25% of this well's",
                          "formation": "WOLFCAMP A",
                          "child": false,
                          "lateral_band_pct": 25,
                          "candidates": 76,
                          "weights": [
                            {
                              "feature": "novi_lateral_length",
                              "weight": 0.4279
                            },
                            {
                              "feature": "novi_bvi_avg",
                              "weight": 0.1391
                            }
                          ],
                          "inputs": {
                            "novi_lateral_length": 7444.415848400713,
                            "novi_bvi_avg": 0.05328801765922385
                          },
                          "eur": {
                            "basis": "Novi's type-curve decline fit (the forecast worker's, as eur: true runs it) of each analog's actual cumulative oil and gas, unscaled, on every 30-day ip_day it has produced (its last 400 when longer), with the dataset's default decline settings (GET /dataset eur.defaults); an analog gets one only with at least 12 months of production (at every 30-day ip_day from 30 to 360), a history no longer than the 50-year horizon and an EUR no lower than its cumulative to date and above its last 30-day cumulative (one not above it is a flat extension, kept only after 90 days without production): 50 of 50 have an oil EUR and 50 a gas EUR",
                            "decline": {
                              "eur_years": 50,
                              "terminal_decline": 0.06,
                              "b_min": 0.5,
                              "b_max": 2.5
                            },
                            "fitted": {
                              "oil": 50,
                              "gas": 50
                            }
                          },
                          "wells": [
                            {
                              "key": "SB173-01173",
                              "distance": 0.368,
                              "well_name": "WINSLOW 25-37 4WA",
                              "operator": "Sample Operator E",
                              "formation": "WOLFCAMP A",
                              "first_prod": "2018-07-31",
                              "lateral_length": 7400,
                              "heel_lon": -101.68563709780273,
                              "heel_lat": 31.733055718384534,
                              "bhl_lon": -101.685469,
                              "bhl_lat": 31.753296,
                              "cum_oil_360": 178956,
                              "cum_oil_720": 256262,
                              "cum_oil_1080": 315668,
                              "cum_gas_360": 273223,
                              "cum_gas_720": 436929,
                              "cum_gas_1080": 583961,
                              "cum_oil_life": 494977,
                              "cum_gas_life": 1108352,
                              "eur_oil": 889020.6596323706,
                              "eur_gas": 2699327.4608316156,
                              "inputs": {
                                "novi_lateral_length": 7400,
                                "novi_bvi_avg": 0.05149718750928755
                              }
                            }
                          ],
                          "coverage": {
                            "ip_day": 810,
                            "k": 50,
                            "nominal": 0.8,
                            "measured": 0.752,
                            "wells": 351,
                            "gate": {
                              "min": 0.7,
                              "max": 0.9,
                              "wells": 300
                            },
                            "shown": true
                          },
                          "spread": {
                            "basis": "actual cumulative production of these 50 model analogs, each scaled to this well's 7,444 ft lateral. Analog spread, not the model's uncertainty: its q10-q90 held 75.2% of 351 held-out wells' day-810 oil (nominal 80%)",
                            "lateral_length_ft": 7444,
                            "wells_considered": 50,
                            "min_wells": 5,
                            "rows": [
                              {
                                "ip_day": 810,
                                "wells": 50,
                                "q10": 216014,
                                "q50": 294424.8,
                                "q90": 366772.9,
                                "forecast": "within"
                              }
                            ]
                          }
                        }
                      },
                      "gas": {
                        "model_num": "M20261022-sampleb-G-d1",
                        "unit": "mcf",
                        "shap": [
                          {
                            "ip_day": 810,
                            "expected_value": 820824.266,
                            "values": {
                              "novi_lateral_length": -220299.582,
                              "novi_tvd": 128037.087,
                              "(other)": 83130.681
                            }
                          }
                        ],
                        "other_weight": 1,
                        "contributing_wells": [],
                        "analogs": {
                          "method": "shap_weighted",
                          "note": "Analog spread, not the model's uncertainty",
                          "basis": "the 50 training wells nearest this forecast in the model's inputs at ip_day 1,080, by distance over standard scores weighted by the model's mean |SHAP|, of the 76 in the same formation, also parents, with a lateral within 25% of this well's",
                          "formation": "WOLFCAMP A",
                          "child": false,
                          "lateral_band_pct": 25,
                          "candidates": 76,
                          "weights": [
                            {
                              "feature": "novi_tvd",
                              "weight": 0.3412
                            },
                            {
                              "feature": "novi_lateral_length",
                              "weight": 0.3131
                            }
                          ],
                          "inputs": {
                            "novi_tvd": 9290,
                            "novi_lateral_length": 7444.415848400713
                          },
                          "eur": {
                            "basis": "Novi's type-curve decline fit (the forecast worker's, as eur: true runs it) of each analog's actual cumulative oil and gas, unscaled, on every 30-day ip_day it has produced (its last 400 when longer), with the dataset's default decline settings (GET /dataset eur.defaults); an analog gets one only with at least 12 months of production (at every 30-day ip_day from 30 to 360), a history no longer than the 50-year horizon and an EUR no lower than its cumulative to date and above its last 30-day cumulative (one not above it is a flat extension, kept only after 90 days without production): 50 of 50 have an oil EUR and 50 a gas EUR",
                            "decline": {
                              "eur_years": 50,
                              "terminal_decline": 0.06,
                              "b_min": 0.5,
                              "b_max": 2.5
                            },
                            "fitted": {
                              "oil": 50,
                              "gas": 50
                            }
                          },
                          "wells": [
                            {
                              "key": "SB317-01336",
                              "distance": 0.3612,
                              "well_name": "CASWELL 31-43 3WA",
                              "operator": "Sample Operator F",
                              "formation": "WOLFCAMP A",
                              "first_prod": "2018-04-04",
                              "lateral_length": 7430,
                              "heel_lon": -102.14975627308573,
                              "heel_lat": 32.16790343813271,
                              "bhl_lon": -102.149556,
                              "bhl_lat": 32.188226,
                              "cum_oil_360": 227456,
                              "cum_oil_720": 346492,
                              "cum_oil_1080": 428377,
                              "cum_gas_360": 488858,
                              "cum_gas_720": 837181,
                              "cum_gas_1080": 1119120,
                              "cum_oil_life": 671333,
                              "cum_gas_life": 2111329,
                              "eur_oil": 1202395.6611442855,
                              "eur_gas": 4870269.844560089,
                              "inputs": {
                                "novi_tvd": 9321,
                                "novi_lateral_length": 7430
                              }
                            }
                          ],
                          "coverage": {
                            "ip_day": 810,
                            "k": 50,
                            "nominal": 0.8,
                            "measured": 0.798,
                            "wells": 351,
                            "gate": {
                              "min": 0.7,
                              "max": 0.9,
                              "wells": 300
                            },
                            "shown": true
                          },
                          "spread": {
                            "basis": "actual cumulative production of these 50 model analogs, each scaled to this well's 7,444 ft lateral. Analog spread, not the model's uncertainty: its q10-q90 held 79.8% of 351 held-out wells' day-810 gas (nominal 80%)",
                            "lateral_length_ft": 7444,
                            "wells_considered": 50,
                            "min_wells": 5,
                            "rows": [
                              {
                                "ip_day": 810,
                                "wells": 50,
                                "q10": 429186.3,
                                "q50": 590684,
                                "q90": 857763.2,
                                "forecast": "within"
                              }
                            ]
                          }
                        }
                      },
                      "water": {
                        "model_num": "M20261022-sampleb-W-d1",
                        "unit": "bbl",
                        "shap": [
                          {
                            "ip_day": 810,
                            "expected_value": 757805.422,
                            "values": {
                              "novi_lateral_length": -189792.755,
                              "novi_bvi_avg": 26144.274,
                              "(other)": 54707.188
                            }
                          }
                        ],
                        "other_weight": 1,
                        "contributing_wells": [],
                        "analogs": {
                          "method": "shap_weighted",
                          "note": "Analog spread, not the model's uncertainty",
                          "basis": "the 50 training wells nearest this forecast in the model's inputs at ip_day 1,080, by distance over standard scores weighted by the model's mean |SHAP|, of the 76 in the same formation, also parents, with a lateral within 25% of this well's",
                          "formation": "WOLFCAMP A",
                          "child": false,
                          "lateral_band_pct": 25,
                          "candidates": 76,
                          "weights": [
                            {
                              "feature": "novi_lateral_length",
                              "weight": 0.472
                            },
                            {
                              "feature": "novi_spacing_lateralcloser_mintangent",
                              "weight": 0.1099
                            }
                          ],
                          "inputs": {
                            "novi_lateral_length": 7444.415848400713,
                            "novi_spacing_lateralcloser_mintangent": 2629.1949114049394
                          },
                          "eur": {
                            "basis": "Novi's type-curve decline fit (the forecast worker's, as eur: true runs it) of each analog's actual cumulative oil and gas, unscaled, on every 30-day ip_day it has produced (its last 400 when longer), with the dataset's default decline settings (GET /dataset eur.defaults); an analog gets one only with at least 12 months of production (at every 30-day ip_day from 30 to 360), a history no longer than the 50-year horizon and an EUR no lower than its cumulative to date and above its last 30-day cumulative (one not above it is a flat extension, kept only after 90 days without production): 50 of 50 have an oil EUR and 50 a gas EUR",
                            "decline": {
                              "eur_years": 50,
                              "terminal_decline": 0.06,
                              "b_min": 0.5,
                              "b_max": 2.5
                            },
                            "fitted": {
                              "oil": 50,
                              "gas": 50
                            }
                          },
                          "wells": [
                            {
                              "key": "SB173-01173",
                              "distance": 0.4221,
                              "well_name": "WINSLOW 25-37 4WA",
                              "operator": "Sample Operator E",
                              "formation": "WOLFCAMP A",
                              "first_prod": "2018-07-31",
                              "lateral_length": 7400,
                              "heel_lon": -101.68563709780273,
                              "heel_lat": 31.733055718384534,
                              "bhl_lon": -101.685469,
                              "bhl_lat": 31.753296,
                              "cum_oil_360": 178956,
                              "cum_oil_720": 256262,
                              "cum_oil_1080": 315668,
                              "cum_gas_360": 273223,
                              "cum_gas_720": 436929,
                              "cum_gas_1080": 583961,
                              "cum_oil_life": 494977,
                              "cum_gas_life": 1108352,
                              "eur_oil": 889020.6596323706,
                              "eur_gas": 2699327.4608316156,
                              "inputs": {
                                "novi_lateral_length": 7400,
                                "novi_spacing_lateralcloser_mintangent": 2863.5642126552702
                              }
                            }
                          ],
                          "coverage": {
                            "ip_day": 810,
                            "k": 50,
                            "nominal": 0.8,
                            "measured": 0.783,
                            "wells": 351,
                            "gate": {
                              "min": 0.7,
                              "max": 0.9,
                              "wells": 300
                            },
                            "shown": true
                          },
                          "spread": {
                            "basis": "actual cumulative production of these 50 model analogs, each scaled to this well's 7,444 ft lateral. Analog spread, not the model's uncertainty: its q10-q90 held 78.3% of 351 held-out wells' day-810 water (nominal 80%)",
                            "lateral_length_ft": 7444,
                            "wells_considered": 50,
                            "min_wells": 5,
                            "rows": [
                              {
                                "ip_day": 810,
                                "wells": 50,
                                "q10": 328782.7,
                                "q50": 498097.6,
                                "q90": 760292.2,
                                "forecast": "within"
                              }
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "text/csv",
                  "description": "The analogs table (format=csv), UTF-8: a header row, then per stream this well and its analogs."
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "502": {
            "$ref": "#/components/responses/WorkerFailed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/plans/{id}/drivers/{design}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        },
        {
          "name": "design",
          "in": "path",
          "required": true,
          "description": "The design's position in the plan's `designs`, from 0.",
          "schema": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9
          },
          "example": 0
        }
      ],
      "get": {
        "operationId": "getPlanDrivers",
        "tags": [
          "Plans"
        ],
        "summary": "Rank a plan's drivers",
        "parameters": [
          {
            "name": "stream",
            "in": "query",
            "description": "The stream whose model is explained: `oil` or `gas`, by default the first the model set serves (oil, else gas). A stream it doesn't serve is a 400 naming those it serves, and on a set serving neither, drivers are a 400. BOE has no model of its own; rank oil's or gas's.",
            "schema": {
              "type": "string",
              "enum": [
                "oil",
                "gas"
              ],
              "default": "oil"
            }
          },
          {
            "name": "ip_day",
            "in": "query",
            "description": "The ip_day to explain: one of the ip_days in the plan's model rows, which are GET /dataset `ip_days` (400 otherwise, with them in `details.allowed`). A value that isn't digits is refused before anything is computed. Default 1080, as GET /plans/{id}/stats.",
            "schema": {
              "type": "integer",
              "default": 1080
            },
            "example": 360
          },
          {
            "name": "include",
            "in": "query",
            "description": "`path` adds the plan's SHAP decision path: `expected_value`, where it starts; each driver's `mean_shap`, its signed mean over the explained wells; and `mean_forecast` and `mean_residual`, where it ends.\n\nPlanDrivers has each. An input a well's row leaves out counts as 0. `expected_value` plus the sum of `mean_shap` equals the mean of each explained well's `expected_value` plus its `values`, to float rounding; adding `mean_residual` gives `mean_forecast`. On a causal model set (GET /model-sets?include=model_type) `mean_residual` can be large: show it as a \"not attributed\" step so the path ends at the forecast. Any other name is a 400 with the allowed one in `details.allowed`.",
            "schema": {
              "type": "string",
              "enum": [
                "path"
              ]
            }
          },
          {
            "name": "scenario",
            "in": "query",
            "description": "On a plan made with scenarios, the alternative to explain: the 100-well cap, `placed` and the means are then over its wells alone.\n\nA scenario plan answers 409 without it, so alternatives are never averaged together; the 409's `details.scenarios` lists the plan's scenario names in plan order, to pick from. An empty name, a name the plan doesn't have, or any name on a plan without scenarios is a 400.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "description": "The fast way to rank what drives a done plan's forecasts: one stream's SHAP at one ip_day for the plan's first 100 placed wells, in plan order, from one model call, and each input's mean |SHAP| over the wells explained, largest first.\n\n**Each well.** Its `expected_value` and `values` equal its explanation's SHAP row for that stream at `ip_day` (formation's one-hot columns summed into `novi_formation`). An input its row leaves out moved that forecast by 0: it counts as 0 in the mean, and `wells` counts the wells whose row has it. A placed well without a forecast (no target formation) is listed with its `error` and left out of `explained` and the means; wells that couldn't be placed aren't listed (GET /plans/{id}?include=wells names them).\n\n**One well.** Its contributing wells, analogs, comparisons and other ip_days are in GET /plans/{id}/wells/{index}/explanations/{design}.\n\n**Caching.** Each design, stream and scenario is explained once, at every ip_day, and kept in memory with the plan, so another ip_day answers without a model call; a restart explains it again.\n\n**Errors.** 409 while the plan runs, when it failed, or for a scenario plan without `scenario`; 404 for an unknown plan or a design index the plan doesn't have.",
        "responses": {
          "200": {
            "description": "The plan's drivers.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanDrivers"
                },
                "examples": {
                  "drivers": {
                    "summary": "stream=oil&ip_day=360 (trimmed)",
                    "value": {
                      "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                      "design": 0,
                      "stream": "oil",
                      "ip_day": 360,
                      "unit": "bbl",
                      "placed": 3,
                      "explained": 2,
                      "drivers": [
                        {
                          "feature": "novi_lateral_length",
                          "mean_abs_shap": 15000,
                          "wells": 2
                        },
                        {
                          "feature": "novi_calc_proppant_per_length",
                          "mean_abs_shap": 6000,
                          "wells": 2
                        },
                        {
                          "feature": "novi_formation",
                          "mean_abs_shap": 3000,
                          "wells": 2
                        },
                        {
                          "feature": "novi_tvd",
                          "mean_abs_shap": 1000,
                          "wells": 1
                        }
                      ],
                      "wells": [
                        {
                          "index": 0,
                          "label": "Plan well 1",
                          "expected_value": 100000,
                          "values": {
                            "novi_lateral_length": 12000,
                            "novi_calc_proppant_per_length": 8000,
                            "novi_formation": -3000,
                            "novi_tvd": 2000
                          }
                        },
                        {
                          "index": 1,
                          "label": "Plan well 2",
                          "expected_value": 100000,
                          "values": {
                            "novi_lateral_length": 18000,
                            "novi_calc_proppant_per_length": 4000,
                            "novi_formation": 3000
                          }
                        },
                        {
                          "index": 2,
                          "label": "Plan well 3",
                          "error": "No forecast to explain: the well needs a target formation."
                        }
                      ]
                    }
                  },
                  "path": {
                    "summary": "include=path&stream=oil&ip_day=360 (trimmed)",
                    "value": {
                      "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                      "design": 0,
                      "stream": "oil",
                      "ip_day": 360,
                      "unit": "bbl",
                      "placed": 3,
                      "explained": 2,
                      "expected_value": 100000,
                      "mean_forecast": 113000,
                      "mean_residual": -9000,
                      "drivers": [
                        {
                          "feature": "novi_lateral_length",
                          "mean_abs_shap": 15000,
                          "mean_shap": 15000,
                          "wells": 2
                        },
                        {
                          "feature": "novi_calc_proppant_per_length",
                          "mean_abs_shap": 6000,
                          "mean_shap": 6000,
                          "wells": 2
                        },
                        {
                          "feature": "novi_formation",
                          "mean_abs_shap": 3000,
                          "mean_shap": 0,
                          "wells": 2
                        },
                        {
                          "feature": "novi_tvd",
                          "mean_abs_shap": 1000,
                          "mean_shap": 1000,
                          "wells": 1
                        }
                      ],
                      "wells": [
                        {
                          "index": 0,
                          "label": "Plan well 1",
                          "expected_value": 100000,
                          "values": {
                            "novi_lateral_length": 12000,
                            "novi_calc_proppant_per_length": 8000,
                            "novi_formation": -3000,
                            "novi_tvd": 2000
                          }
                        },
                        {
                          "index": 1,
                          "label": "Plan well 2",
                          "expected_value": 100000,
                          "values": {
                            "novi_lateral_length": 18000,
                            "novi_calc_proppant_per_length": 4000,
                            "novi_formation": 3000
                          }
                        },
                        {
                          "index": 2,
                          "label": "Plan well 3",
                          "error": "No forecast to explain: the well needs a target formation."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "502": {
            "$ref": "#/components/responses/WorkerFailed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/plans/{id}/typecurve/{design}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        },
        {
          "name": "design",
          "in": "path",
          "required": true,
          "description": "The design's position in the plan's `designs`, from 0.",
          "schema": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9
          },
          "example": 0
        }
      ],
      "get": {
        "operationId": "getPlanTypeCurve",
        "tags": [
          "Plans"
        ],
        "summary": "Build a type curve from a plan's forecasts",
        "parameters": [
          {
            "name": "streams",
            "in": "query",
            "description": "The streams, comma-separated, each once: `oil`, `gas`, `water` and `boe`, as `oil,boe`. Absent or empty: the plan's streams, then `boe` (all four on a plan with oil, gas and water). Another name, or one named twice, is a 400.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "measures",
            "in": "query",
            "description": "`cum`, each well's cumulative at the ip_day, and `rate`, its average daily rate over the step ending there (the first step from day 0), comma-separated, as `rate` or `cum,rate`. Absent or empty: both. Another name, or one named twice, is a 400.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "normalize_lateral_ft",
            "in": "query",
            "description": "Scale each well to this many ft of lateral before the statistics: its value × normalize_lateral_ft / its `lateral_length_ft` (as GET /plans/{id}?include=wells serves it). A plain decimal from 100 to 20,000, as 1000 for per 1,000 ft. Absent: unscaled, and the answer's `normalize_lateral_ft` is null.",
            "schema": {
              "type": "number",
              "minimum": 100,
              "maximum": 20000
            }
          },
          {
            "name": "pooled",
            "in": "query",
            "description": "`true`, with normalize_lateral_ft only (without it, a 400 on pooled): each series also gets `pooled`, Σ value / Σ lateral × normalize_lateral_ft over the wells with a value at the ip_day, as POST /wells/typecurve gives it. Absent or `false`: no pooled key.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "group_by",
            "in": "query",
            "description": "One curve per group, the 12 with the most wells used kept and the rest counted in `groups_left_out`. Any other value is a 400.\n\n- `formation`: each well's formation; ties by name, wells without one last.\n- `pad`: each pad key; ties by key, wells without a pad as `group: null`; with `scenario`, among its wells. A plan whose wells name no pads is a 400: send wells[].pad.",
            "schema": {
              "type": "string",
              "enum": [
                "formation",
                "pad"
              ]
            }
          },
          {
            "name": "scenario",
            "in": "query",
            "description": "On a plan made with scenarios, the alternative to aggregate: `wells`, `used` and the curves are then over its wells alone. A scenario plan answers 409 without it, so alternatives are never averaged together; the 409's `details.scenarios` lists the plan's scenario names in plan order, to pick from. An empty name, a name the plan doesn't have, or any name on a plan without scenarios is a 400.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "description": "A done plan's forecasts for one design as type curves, in POST /wells/typecurve's shape. It carries an `ETag`: send it as `If-None-Match` for a 304.\n\n**Values.** Each well's value is its served forecast for the design (the curve GET /plans/{id}/wells/{index} serves; exports call it P50) at each forecast ip_day: each stream's cumulative, BOE as oil + gas / 6 (null when either is), and `rate`, the step's average daily rate.\n\n**Statistics.** At each ip_day, `wells` counts the wells with a value; `mean` is their plain mean and q10, q50 and q90 their quantiles, linear between ranks as GET /plans/{id}/stats takes them, not the plan's P10 and P90 bands. `min_wells` is 1.\n\n**Counts.** `wells` counts the wells in scope (the plan's, or the scenario's), `used` those with a forecast for the design, and `excluded.no_forecast` the rest (not placed, or the forecast failed); the other `excluded` counts are 0. A well whose stream failed stays in `used` but leaves that stream's `wells`.\n\n**Errors.** 409 while the plan runs, when it failed, or for a scenario plan without `scenario`; 404 for an unknown plan or a design index the plan doesn't have.",
        "responses": {
          "200": {
            "description": "The plan's type curves.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TypeCurveResponse"
                },
                "examples": {
                  "oil": {
                    "summary": "streams=oil&measures=cum on a three-well plan whose third well has no target formation (trimmed to three ip_days)",
                    "value": {
                      "wells": 3,
                      "used": 2,
                      "excluded": {
                        "no_production": 0,
                        "no_lateral": 0,
                        "no_location": 0,
                        "no_forecast": 1
                      },
                      "normalize_lateral_ft": null,
                      "min_wells": 1,
                      "units": {
                        "oil": "bbl",
                        "gas": "mcf",
                        "water": "bbl",
                        "boe": "BOE",
                        "rate": "per day"
                      },
                      "ip_days": [
                        30,
                        360,
                        1080
                      ],
                      "curves": [
                        {
                          "group": null,
                          "wells": 2,
                          "streams": {
                            "oil": {
                              "cum": {
                                "wells": [
                                  2,
                                  2,
                                  2
                                ],
                                "mean": [
                                  13078.5,
                                  114843.9,
                                  209536.3
                                ],
                                "q10": [
                                  11094.4,
                                  96692.3,
                                  175762.3
                                ],
                                "q50": [
                                  13078.5,
                                  114843.9,
                                  209536.3
                                ],
                                "q90": [
                                  15062.6,
                                  132995.4,
                                  243310.2
                                ]
                              }
                            }
                          }
                        }
                      ],
                      "groups_left_out": 0
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/plans/{id}/economics": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        }
      ],
      "post": {
        "operationId": "createPlanEconomics",
        "tags": [
          "Economics"
        ],
        "summary": "Price a whole plan in the background",
        "description": "Prices every well of a done plan under one design (and, on a scenario plan, one scenario) in the background, as POST /economics prices a plan well: one call for thousands of wells, and no client sums.\n\n**The job.** It answers 202 with a PlanEconomicsJob and its `Location`; GET /plans/{id}/economics/{job_id}?wait=25 until `status` is `done` or `error`. Jobs belong to the request tenant. An `Idempotency-Key` replays the first job for the same plan and body.\n\n**Totals.** `totals` and each group sum their priced wells' monthly cash flows as if every well came online together, then take NPV, IRR and payback of that sum, so the pads' `npv` and `capex` add up to the totals'. An unpriced well counts in `wells`, not `priced`; the first (by plan index) names the `reason`. A group's economics are null only when none of its wells is priced (POST /economics instead gives a scenario with any unpriced well none).\n\n**Groups.** No group is folded.\n\n- `group_by: [\"pad\"]`: pad keys in plan order of each pad's first well, wells without a pad last as `key: null`. A plan whose wells name no pad is a 400: send wells[].pad on POST /plans.\n- `group_by: [\"formation\"]`: GET /formations order, wells without one last.\n- `include: [\"wells\"]` adds a row per well in plan order; `\"breakeven\"`, each group's and the totals' flat oil and gas breakeven prices, as POST /economics finds them.\n\n**Limits.** At most 4 jobs run at once per tenant, across model sets and server tasks; the next is a 409 with `Retry-After: 1`. A job still pricing 10 minutes after it was posted, its wait for a server included, fails (`unavailable`): price one scenario or fewer groups. One no server took fails a minute later. Jobs are kept an hour after they finish, in Redis (shared by every server task) or the server's memory; with Redis, a job whose server stops runs again on another.\n\n**Errors.** The plan's 409s come first (running, failed, or made without `eur: true`), then `design`, `scenario`, `group_by`, `include`, `conventions`, `deck_id` and `deck`, in that order; `design`, `scenario`, `conventions` and the deck are checked as POST /economics checks them.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "requestBody": {
          "required": false,
          "description": "What to price, and how to group it.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlanEconomicsRequest"
              },
              "examples": {
                "pads": {
                  "summary": "Every pad and landing zone, with each well",
                  "value": {
                    "design": 0,
                    "group_by": [
                      "pad",
                      "formation"
                    ],
                    "include": [
                      "wells"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job, running (or, replaying an Idempotency-Key, as it is now).",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanEconomicsJob"
                },
                "example": {
                  "id": "6b2e4f0a-1c3d-4e5f-8a7b-9c0d1e2f3a4b",
                  "plan_id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                  "status": "running",
                  "created_at": "2026-11-09T18:04:11.000Z",
                  "finished_at": null,
                  "seconds": 0.2,
                  "result": null,
                  "error": null,
                  "links": {
                    "self": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630/economics/6b2e4f0a-1c3d-4e5f-8a7b-9c0d1e2f3a4b"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The plan is running, failed or was made without `eur: true`; the Idempotency-Key was already used with a different body; or 4 plan economics jobs are already running for the tenant (with `Retry-After: 1`).",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/plans/{id}/economics/{job_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        },
        {
          "name": "job_id",
          "in": "path",
          "required": true,
          "description": "The job id POST /plans/{id}/economics answered with.",
          "schema": {
            "type": "string",
            "format": "uuid"
          },
          "example": "6b2e4f0a-1c3d-4e5f-8a7b-9c0d1e2f3a4b"
        }
      ],
      "get": {
        "operationId": "getPlanEconomics",
        "tags": [
          "Economics"
        ],
        "summary": "Get a plan's economics job",
        "description": "A plan economics job: its status, then `result` (the plan priced) or `error`. Running, it answers with `Retry-After: 1`: send `wait` instead of polling. Done or failed, it carries an `ETag` for `If-None-Match` (304). 404 for an unknown or expired id, another tenant's job, or one of another plan or model set.",
        "parameters": [
          {
            "name": "wait",
            "in": "query",
            "description": "Use this instead of polling: on a running job, the answer is held until it finishes, or this many seconds pass.\n\nWhole seconds, 1 to 25 (400 otherwise). The answer is what a GET without `wait` would get when the wait ends, `Retry-After` included; a finished job answers at once. A client that disconnects ends the wait.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The job.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanEconomicsJob"
                },
                "examples": {
                  "running": {
                    "summary": "Running",
                    "value": {
                      "id": "6b2e4f0a-1c3d-4e5f-8a7b-9c0d1e2f3a4b",
                      "plan_id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                      "status": "running",
                      "created_at": "2026-11-09T18:04:11.000Z",
                      "finished_at": null,
                      "seconds": 0.2,
                      "result": null,
                      "error": null,
                      "links": {
                        "self": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630/economics/6b2e4f0a-1c3d-4e5f-8a7b-9c0d1e2f3a4b"
                      }
                    }
                  },
                  "done": {
                    "summary": "Done: three wells on two pads, with each well",
                    "value": {
                      "id": "6b2e4f0a-1c3d-4e5f-8a7b-9c0d1e2f3a4b",
                      "plan_id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                      "status": "done",
                      "created_at": "2026-11-09T18:04:11.000Z",
                      "finished_at": "2026-11-09T18:04:12.000Z",
                      "seconds": 1,
                      "result": {
                        "plan_id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                        "design": 0,
                        "scenario": null,
                        "deck": {
                          "deck_id": "prototype-midland-flat",
                          "version": 1,
                          "name": "Illustrative Midland flat-price deck",
                          "overrides": [],
                          "discount_rate": 0.25,
                          "values": {
                            "oil_price": 75,
                            "oil_differential": 4,
                            "gas_price": 3.5,
                            "gas_differential": 1,
                            "ngl_price": 26,
                            "ngl_yield_bbl_per_mmcf": 130,
                            "shrink": 0.8,
                            "opex_oil": 5.5,
                            "opex_gas": 0.5,
                            "opex_water": 0.6,
                            "royalty": 0.25,
                            "severance_oil": 0.046,
                            "severance_gas": 0.075,
                            "ad_valorem": 0.025,
                            "capex_per_well": 2500000,
                            "capex_drilling_per_ft": 150,
                            "capex_stimulation_per_ft": 125,
                            "capex_proppant_per_lb": 0.08,
                            "capex_fluid_per_bbl": 3,
                            "discount_rate": 0.25
                          }
                        },
                        "conventions": "prototype",
                        "totals": {
                          "wells": 3,
                          "priced": 3,
                          "capex": 27963750,
                          "npv": 43897658.19048103,
                          "irr_pct": 342.5427164643585,
                          "payback_months": 5.696026288988866,
                          "reason": null
                        },
                        "groups": {
                          "pad": [
                            {
                              "key": "1",
                              "wells": 2,
                              "priced": 2,
                              "capex": 18642500,
                              "npv": 32267706.231690783,
                              "irr_pct": 408.8594386951259,
                              "payback_months": 5.273689847778136,
                              "reason": null
                            },
                            {
                              "key": "2",
                              "wells": 1,
                              "priced": 1,
                              "capex": 9321250,
                              "npv": 11629951.958790233,
                              "irr_pct": 233.26917742884734,
                              "payback_months": 6.785050128553182,
                              "reason": null
                            }
                          ],
                          "formation": [
                            {
                              "key": "WOLFCAMP A",
                              "wells": 2,
                              "priced": 2,
                              "capex": 18642500,
                              "npv": 30351708.473153953,
                              "irr_pct": 365.5601403288541,
                              "payback_months": 5.537210212728964,
                              "reason": null
                            },
                            {
                              "key": "WOLFCAMP B",
                              "wells": 1,
                              "priced": 1,
                              "capex": 9321250,
                              "npv": 13545949.717327068,
                              "irr_pct": 299.6358678615102,
                              "payback_months": 6.039452850526949,
                              "reason": null
                            }
                          ]
                        },
                        "wells": [
                          {
                            "index": 0,
                            "label": "Plan well 1",
                            "pad": "1",
                            "formation": "WOLFCAMP A",
                            "capex": 9321250,
                            "npv": 18721756.514363706,
                            "irr_pct": 545.0611242112366,
                            "payback_months": 4.6796713031586865,
                            "reason": null
                          },
                          {
                            "index": 1,
                            "label": "Plan well 2",
                            "pad": "1",
                            "formation": "WOLFCAMP B",
                            "capex": 9321250,
                            "npv": 13545949.717327068,
                            "irr_pct": 299.6358678615102,
                            "payback_months": 6.039452850526949,
                            "reason": null
                          },
                          {
                            "index": 2,
                            "label": "Plan well 3",
                            "pad": "2",
                            "formation": "WOLFCAMP A",
                            "capex": 9321250,
                            "npv": 11629951.958790233,
                            "irr_pct": 233.26917742884734,
                            "payback_months": 6.785050128553182,
                            "reason": null
                          }
                        ]
                      },
                      "error": null,
                      "links": {
                        "self": "/api/v1/plans/9cae6c80-cbd7-4339-b1c0-1cac810d0630/economics/6b2e4f0a-1c3d-4e5f-8a7b-9c0d1e2f3a4b"
                      }
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/plans/{id}/export": {
      "parameters": [
        {
          "$ref": "#/components/parameters/PlanId"
        }
      ],
      "get": {
        "operationId": "exportPlan",
        "tags": [
          "Plans"
        ],
        "summary": "Export a plan",
        "description": "The plan as a zip of six CSVs, built while you wait and stored uncompressed with its length, so clients can show progress. New clients should use POST /exports: its `plan_tables` preset writes the same CSVs as a job, with monthly volumes to EUR and a file that resumes.\n\n**Files.** The six CSVs:\n\n- `wells.csv`: inputs, TVD, heel and pad, plus each well's values and their layers for completions, TIL dates, landings and EUR settings set below the plan (water's with `eur_water`).\n- `designs.csv`: each design's completions and their source.\n- `forecast.csv`: cumulative oil, gas and water per well by design and ip_day, plus each design's plan total.\n- `neighbors.csv`, `calc_features.csv` and `subsurface.csv`.\n\n**Errors.** 409 while the plan runs or when it failed, and for two kinds of plan, which POST /exports with `\"source\": {\"plan\": \"<id>\"}` takes:\n\n- A plan made with scenarios, whose Plan total rows would add its alternatives together: send `scenario`, one export per scenario.\n- A plan of more than 10,000 forecasts (wells × designs), too big for one answer. Made with scenarios, it also sends `scenario`; the 409's `details.scenarios` says how many.",
        "responses": {
          "200": {
            "description": "The zip.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Content-Disposition": {
                "$ref": "#/components/headers/ContentDisposition"
              }
            },
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "application/zip",
                  "description": "Zip archive."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The plan is running or failed; it was made with scenarios, whose Plan total rows would add its alternatives together; or it has more than 10,000 forecasts, wells × designs. Export the last two with POST /exports. A plan over the cap that was made with scenarios takes `scenario` too, one export per scenario, and `details.scenarios` says how many it has.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "size": {
                    "summary": "More than 10,000 forecasts",
                    "value": {
                      "error": {
                        "code": "conflict",
                        "message": "Plan 9cae6c80-cbd7-4339-b1c0-1cac810d0630 has 12,000 forecasts (wells × designs), more than the 10,000 GET /plans/{id}/export zips in one answer; export it with POST /exports and \"source\": {\"plan\": \"9cae6c80-cbd7-4339-b1c0-1cac810d0630\"}",
                        "details": {
                          "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                          "forecasts": 12000,
                          "max": 10000
                        }
                      },
                      "request_id": "682a49e1-e4ab-4ead-a25f-c689db67e812"
                    }
                  },
                  "scenarios": {
                    "summary": "More than 10,000 forecasts, made with scenarios",
                    "value": {
                      "error": {
                        "code": "conflict",
                        "message": "Plan 9cae6c80-cbd7-4339-b1c0-1cac810d0630 has 12,000 forecasts (wells × designs), more than the 10,000 GET /plans/{id}/export zips in one answer; export it with POST /exports and \"source\": {\"plan\": \"9cae6c80-cbd7-4339-b1c0-1cac810d0630\"} and \"scenario\", one export per scenario (the plan has 2)",
                        "details": {
                          "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                          "forecasts": 12000,
                          "max": 10000,
                          "scenarios": 2
                        }
                      },
                      "request_id": "380199a4-ac1e-4a5e-8bab-ccd276b18298"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/export-formats": {
      "get": {
        "operationId": "listExportFormats",
        "tags": [
          "Exports"
        ],
        "summary": "List export tables and presets",
        "description": "What an export can hold: tables (file, columns, options, rows), presets and the default one, P-levels, this server's retention and queue limits, and callbacks. Not cached: availability follows the plan and the worker.\n\n**A plan.** With `plan`, availability, reasons and defaults are that plan's.\n\n- Made without `eur: true`: the `eur` table and the presets that need it are unavailable, and `monthly` runs to the forecast's last month.\n- Made with `bands: true`: P10 and P90 are available for `p_levels`.\n- Running or failed: every preset and table is unavailable, with the reason, as POST /exports answers 409.\n\n**A wells source.** Without `plan`, `eur` and `eur_water` describe a POST /exports `source.wells` with those settings, as a plan made with them would be; without any of the three, as a plan with EUR.\n\n- `eur=false` drops the `forecast` table's EUR columns and makes the `eur` table and the presets that need EUR unavailable. `eur_water=true` adds water's EUR columns to `eur` and `forecast`.\n- The `arps` b_min and b_max defaults ignore a wells source's `decline` bounds, a `well` column holds the wells' labels, and `p_levels` is P50 alone.\n- Reasons say why in plain words; POST /exports' refusal also names the field to send.\n- Build `columns` from this answer: POST /exports refuses a column it doesn't list (409 for an oil or gas EUR column or `eur_days` without EUR, else 400, water's EUR columns without `eur_water` included).\n\n**An export's scope.** With `plan`, `scenario` and `designs` scope an export as on POST /exports. Tables, columns, P-levels, defaults and limits stay the plan's.\n\n- The drivers, valnav and combocurve presets count the scope: drivers its wells × designs, valnav and combocurve its designs and its wells' Well IDs. Their refusals then say \"this export has\", not \"this plan has\"; scenario reasons keep \"this plan has\".\n- With two or more scenarios, the presets that write Plan total rows (`engineer`, `monthly`, `plan_tables`) are unavailable until `scenario` picks one, since POST /exports refuses Plan total rows across scenarios (400). So are combocurve, valnav and aries, whose files carry no scenario.\n\n**The worker.** The `arps` table and preset need the forecast worker's multi-segment Arps fit. The `aries` preset (no tables: an ARIES text file) needs a plan made with `eur: true` and a worker that writes ARIES and passed its startup check. Each gives the reason when unavailable.\n\n**Errors.** With `plan`, a plan this server can't read yet answers 409, as POST /exports would: one running on another server, or one that failed before it was saved.\n\n**Tenant.** With plan, a missing or other-tenant plan is a 404; without plan, no tenant is read.",
        "parameters": [
          {
            "name": "plan",
            "in": "query",
            "description": "A plan id from POST /plans: availability and defaults for that plan. Without it and without `eur` or `eur_water`, as for a plan with EUR.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "eur",
            "in": "query",
            "description": "A wells source's `source.eur`: `false` describes wells forecast without EUR, and `true` or leaving it out, with EUR, though a POST /exports wells source that leaves `source.eur` out has EUR only when this server's forecast worker does, or when it sends `eur_water` or decline settings. Not with `plan` (400: the plan's own settings answer). Any other nonempty value is a 400.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "eur_water",
            "in": "query",
            "description": "A wells source's `source.eur_water`: `true` adds water's EUR columns and turns EUR on, as on a wells source, so `eur=false` beside it is a 400. Not with `plan` (400). Any other nonempty value is a 400.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "scenario",
            "in": "query",
            "description": "With `plan`, on a plan made with scenarios: one scenario's name as POST /exports `scenario` takes it, exactly as the plan's `scenarios` list it, URL-encoded (`660 ft` is `scenario=660%20ft`).\n\nThe drivers, valnav and combocurve presets, and include=identity's `unnamed_wells`, then count only its wells; the presets that write Plan total rows, and combocurve, valnav and aries, aren't refused for mixing scenarios. A name the plan lacks, or any name on a plan without scenarios, is a 400 on scenario with the plan's scenarios in `details.scenarios`. Without `plan`, a 400.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            }
          },
          {
            "name": "designs",
            "in": "query",
            "description": "With `plan`: design indexes from 0, comma-separated, as POST /exports `designs` takes them (`designs=0,2`). The drivers, valnav and combocurve presets then count only those designs.\n\nA repeated index counts once; one past the plan's designs is a 400 on designs with the plan's count in `details.designs`. Without `plan`, a 400. It picks no scenario: with two or more, the presets that write Plan total rows, and combocurve, valnav and aries, stay unavailable without `scenario`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include",
            "in": "query",
            "description": "Adds `identity`, `table_rules`, `categories` or `groups` to the answer, comma-separated or repeated, each once. Any other value is a 400 with details.field include.\n\n- `identity`: the fields POST /exports `identity` takes, each with its values or format, default and what it writes; with `plan`, `unnamed_wells`, how many wells `well_id: \"name\"` writes as their plan label (Plan well N): no name, or a name equal to that label.\n  - Each preset gains `identity`, the fields it reads (aries and combocurve: well_id and start_date; valnav: all three; a planned preset: those it will read; else empty), and `note`, a sentence to show beside it, if it has one.\n  - Each table gains `identity`, the fields POST /exports takes with it (valnav_decline: all three; combocurve_wells and combocurve_forecast: well_id and start_date; else empty), even when a preset writing it is unavailable.\n- `table_rules`: each table's `p_levels` and `fixed_columns`, from the rules POST /exports refuses by. Build `p_levels`, `reserves_categories` and `columns` from them.\n- `categories`: the presets by results category, in display order, with id, title and preset ids. A category's one-click download is its first preset `presets` lists as available (for the plan, when sent); the rest are its menu.\n- `groups`: the presets to offer a person choosing an export, by group, in display order, with id, title and preset ids, the same with or without `plan`, `eur` or `eur_water`. A preset in no group is still a valid POST /exports `preset`.\n\nAvailability and reasons stay on `presets`.",
            "schema": {
              "type": "string",
              "enum": [
                "identity",
                "table_rules",
                "categories",
                "groups",
                "identity,table_rules",
                "identity,categories",
                "identity,groups",
                "table_rules,identity",
                "table_rules,categories",
                "table_rules,groups",
                "categories,identity",
                "categories,table_rules",
                "categories,groups",
                "groups,identity",
                "groups,table_rules",
                "groups,categories",
                "identity,table_rules,categories",
                "identity,table_rules,groups",
                "identity,categories,table_rules",
                "identity,categories,groups",
                "identity,groups,table_rules",
                "identity,groups,categories",
                "table_rules,identity,categories",
                "table_rules,identity,groups",
                "table_rules,categories,identity",
                "table_rules,categories,groups",
                "table_rules,groups,identity",
                "table_rules,groups,categories",
                "categories,identity,table_rules",
                "categories,identity,groups",
                "categories,table_rules,identity",
                "categories,table_rules,groups",
                "categories,groups,identity",
                "categories,groups,table_rules",
                "groups,identity,table_rules",
                "groups,identity,categories",
                "groups,table_rules,identity",
                "groups,table_rules,categories",
                "groups,categories,identity",
                "groups,categories,table_rules",
                "identity,table_rules,categories,groups",
                "identity,table_rules,groups,categories",
                "identity,categories,table_rules,groups",
                "identity,categories,groups,table_rules",
                "identity,groups,table_rules,categories",
                "identity,groups,categories,table_rules",
                "table_rules,identity,categories,groups",
                "table_rules,identity,groups,categories",
                "table_rules,categories,identity,groups",
                "table_rules,categories,groups,identity",
                "table_rules,groups,identity,categories",
                "table_rules,groups,categories,identity",
                "categories,identity,table_rules,groups",
                "categories,identity,groups,table_rules",
                "categories,table_rules,identity,groups",
                "categories,table_rules,groups,identity",
                "categories,groups,identity,table_rules",
                "categories,groups,table_rules,identity",
                "groups,identity,table_rules,categories",
                "groups,identity,categories,table_rules",
                "groups,table_rules,identity,categories",
                "groups,table_rules,categories,identity",
                "groups,categories,identity,table_rules",
                "groups,categories,table_rules,identity"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "Tables, presets and limits.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportFormats"
                },
                "example": {
                  "parquet": {
                    "available": true,
                    "load_kits": [
                      "snowflake",
                      "databricks"
                    ]
                  },
                  "aries": {
                    "compat": [
                      "fixed",
                      "fe"
                    ],
                    "default_compat": "fixed"
                  },
                  "tables": [
                    {
                      "id": "monthly",
                      "title": "Monthly volumes",
                      "file": "monthly.csv",
                      "description": "Each well's forecast by 30-day month on production: the model's 36 months, then its EUR's decline to the EUR day",
                      "needs_eur": false,
                      "available": true,
                      "reason": null,
                      "columns": [
                        {
                          "name": "well",
                          "unit": null,
                          "description": "The plan well: its name, else Plan well 12",
                          "default": true,
                          "stream": null
                        },
                        {
                          "name": "design",
                          "unit": null,
                          "description": "The completion design",
                          "default": true,
                          "stream": null
                        },
                        {
                          "name": "p_level",
                          "unit": null,
                          "description": "P50, the point forecast",
                          "default": true,
                          "stream": null
                        }
                      ],
                      "options": [
                        {
                          "name": "horizon",
                          "title": "Horizon",
                          "type": "enum",
                          "values": [
                            "eur",
                            "forecast"
                          ],
                          "default": "eur",
                          "description": "EUR runs each well to its EUR day, 608 30-day months from first production at 50 years; Forecast stops at the forecast's last month. EUR needs a plan made with EUR"
                        },
                        {
                          "name": "values",
                          "title": "Values",
                          "type": "enum[]",
                          "values": [
                            "volume",
                            "cumulative",
                            "rate"
                          ],
                          "default": [
                            "volume",
                            "cumulative"
                          ],
                          "description": "The columns for each stream: the month's volume, the cumulative at its end, and the average daily rate"
                        },
                        {
                          "name": "totals",
                          "title": "Plan totals",
                          "type": "boolean",
                          "default": true,
                          "description": "Plan total rows for each design and month, after the wells; on by default with more than one well. A total is blank where any well's value is, so no total leaves a well out; wells without a forecast for the design aren't in its totals"
                        }
                      ],
                      "rows": "One per well, design and month; then Plan total rows per design and month",
                      "parquet": true
                    },
                    {
                      "id": "arps",
                      "title": "Arps parameters",
                      "file": "arps.csv",
                      "description": "Each forecast curve as multi-segment Arps declines (optional ramp, hyperbolics, terminal exponential) to its EUR years and terminal decline, or Novi's defaults without EUR",
                      "needs_eur": false,
                      "available": true,
                      "reason": null,
                      "columns": [
                        {
                          "name": "well",
                          "unit": null,
                          "description": "The plan well: its name, else Plan well 12",
                          "default": true,
                          "stream": null
                        },
                        {
                          "name": "design",
                          "unit": null,
                          "description": "The completion design",
                          "default": true,
                          "stream": null
                        },
                        {
                          "name": "p_level",
                          "unit": null,
                          "description": "P50, the point forecast",
                          "default": true,
                          "stream": null
                        }
                      ],
                      "options": [
                        {
                          "name": "segments",
                          "title": "Segments",
                          "type": "integer",
                          "min": 1,
                          "max": 4,
                          "default": 2,
                          "description": "Hyperbolic segments before the terminal exponential"
                        },
                        {
                          "name": "ramp",
                          "title": "Ramp",
                          "type": "boolean",
                          "default": false,
                          "description": "Start with a linear ramp to the peak rate within the first 90 days"
                        },
                        {
                          "name": "reconcile",
                          "title": "Segment fitting",
                          "type": "enum",
                          "values": [
                            "independent",
                            "forward"
                          ],
                          "default": "forward",
                          "description": "Forward, the default where this server offers it, rescales each later segment so its rate starts where the one before stops. Independent fits each segment on its own"
                        },
                        {
                          "name": "b_min",
                          "title": "Minimum b",
                          "type": "number",
                          "min": 0.5,
                          "max": 2.5,
                          "default": 0.5,
                          "description": "The lowest b a hyperbolic may take; these bounds are the table's own, not the EUR fit's"
                        },
                        {
                          "name": "b_max",
                          "title": "Maximum b",
                          "type": "number",
                          "min": 0.5,
                          "max": 2.5,
                          "default": 2.5,
                          "description": "The highest b a hyperbolic may take, above the lowest"
                        },
                        {
                          "name": "exponential_units",
                          "title": "Terminal decline units",
                          "type": "enum",
                          "values": [
                            "annual",
                            "per_day"
                          ],
                          "default": "annual",
                          "description": "The exponential row's declines. Annual writes the terminal decline as d_tangent and d_secant and its nominal rate as d_nominal, all per year. Per day writes d_tangent per day and leaves the others blank"
                        }
                      ],
                      "rows": "One per well, design, stream and segment; one error row per curve without a fit",
                      "parquet": true
                    },
                    {
                      "id": "eur",
                      "title": "EUR summary",
                      "file": "eur.csv",
                      "description": "EUR per well and design, with the decline settings and the reported decline fit",
                      "needs_eur": true,
                      "available": true,
                      "reason": null,
                      "columns": [
                        {
                          "name": "well",
                          "unit": null,
                          "description": "The plan well: its name, else Plan well 12",
                          "default": true,
                          "stream": null
                        },
                        {
                          "name": "design",
                          "unit": null,
                          "description": "The completion design",
                          "default": true,
                          "stream": null
                        },
                        {
                          "name": "p_level",
                          "unit": null,
                          "description": "P50, the point forecast",
                          "default": true,
                          "stream": null
                        }
                      ],
                      "options": [],
                      "rows": "One per well and design",
                      "parquet": true
                    },
                    {
                      "id": "wells",
                      "title": "Wells",
                      "file": "wells.csv",
                      "description": "Well locations, laterals, depths and neighbors",
                      "needs_eur": false,
                      "available": true,
                      "reason": null,
                      "columns": [
                        {
                          "name": "well",
                          "unit": null,
                          "description": "The plan well: its name, else Plan well 12",
                          "default": true,
                          "stream": null
                        },
                        {
                          "name": "shl_lon",
                          "unit": "deg",
                          "description": "Surface hole longitude",
                          "default": true,
                          "stream": null
                        },
                        {
                          "name": "shl_lat",
                          "unit": "deg",
                          "description": "Surface hole latitude",
                          "default": true,
                          "stream": null
                        }
                      ],
                      "options": [],
                      "rows": "One per well",
                      "parquet": true
                    },
                    {
                      "id": "designs",
                      "title": "Designs",
                      "file": "designs.csv",
                      "description": "Each design's completions, and what each formation's wells were forecast with",
                      "needs_eur": false,
                      "available": true,
                      "reason": null,
                      "columns": [
                        {
                          "name": "design",
                          "unit": null,
                          "description": "The completion design",
                          "default": true,
                          "stream": null
                        },
                        {
                          "name": "formation",
                          "unit": null,
                          "description": "Blank on the design's own row; else the formation its values apply to",
                          "default": true,
                          "stream": null
                        },
                        {
                          "name": "fluid_bbl_ft",
                          "unit": "bbl/ft",
                          "description": "Fluid per lateral ft",
                          "default": true,
                          "stream": null
                        }
                      ],
                      "options": [],
                      "rows": "One per design, plus one per design and formation",
                      "parquet": true
                    },
                    {
                      "id": "forecast",
                      "title": "Forecast",
                      "file": "forecast.csv",
                      "description": "Cumulative oil, gas and water at each forecast ip day, per well and design",
                      "needs_eur": false,
                      "available": true,
                      "reason": null,
                      "columns": [
                        {
                          "name": "design",
                          "unit": null,
                          "description": "The completion design",
                          "default": true,
                          "stream": null
                        },
                        {
                          "name": "well",
                          "unit": null,
                          "description": "The plan well, or Plan total",
                          "default": true,
                          "stream": null
                        },
                        {
                          "name": "ip_day",
                          "unit": "day",
                          "description": "Days on production",
                          "default": true,
                          "stream": null
                        }
                      ],
                      "options": [],
                      "rows": "One per well, design and ip day; then Plan total rows",
                      "parquet": false
                    },
                    {
                      "id": "neighbors",
                      "title": "Neighbors",
                      "file": "neighbors.csv",
                      "description": "Each well's spacing neighbors, with the spacing model's columns",
                      "needs_eur": false,
                      "available": true,
                      "reason": null,
                      "columns": null,
                      "options": [],
                      "rows": "One per well and neighbor",
                      "parquet": false
                    },
                    {
                      "id": "calc_features",
                      "title": "Calc features",
                      "file": "calc_features.csv",
                      "description": "Each well's calculated model features",
                      "needs_eur": false,
                      "available": true,
                      "reason": null,
                      "columns": null,
                      "options": [],
                      "rows": "One per well",
                      "parquet": false
                    },
                    {
                      "id": "subsurface",
                      "title": "Subsurface",
                      "file": "subsurface.csv",
                      "description": "Subsurface grid values at each well",
                      "needs_eur": false,
                      "available": true,
                      "reason": null,
                      "columns": null,
                      "options": [],
                      "rows": "One per well",
                      "parquet": false
                    }
                  ],
                  "presets": [
                    {
                      "id": "engineer",
                      "title": "Forecast and EUR",
                      "description": "Monthly volumes to EUR, EUR per well, wells and designs",
                      "tables": [
                        {
                          "table": "monthly",
                          "horizon": "eur"
                        },
                        {
                          "table": "eur"
                        },
                        {
                          "table": "wells"
                        },
                        {
                          "table": "designs"
                        }
                      ],
                      "available": true,
                      "reason": null,
                      "media_type": "application/zip",
                      "contents": "tables"
                    },
                    {
                      "id": "monthly",
                      "title": "Monthly volumes to EUR",
                      "description": "Monthly volumes to EUR, EUR per well and wells",
                      "tables": [
                        {
                          "table": "monthly",
                          "horizon": "eur"
                        },
                        {
                          "table": "eur"
                        },
                        {
                          "table": "wells"
                        }
                      ],
                      "available": true,
                      "reason": null,
                      "media_type": "application/zip",
                      "contents": "tables"
                    },
                    {
                      "id": "plan_tables",
                      "title": "Wells and spacing",
                      "description": "Wells, designs, neighbors, model inputs, subsurface values and cumulative volumes by day",
                      "tables": [
                        {
                          "table": "wells"
                        },
                        {
                          "table": "designs"
                        },
                        {
                          "table": "forecast"
                        },
                        {
                          "table": "neighbors"
                        },
                        {
                          "table": "calc_features"
                        },
                        {
                          "table": "subsurface"
                        }
                      ],
                      "available": true,
                      "reason": null,
                      "media_type": "application/zip",
                      "contents": "tables"
                    },
                    {
                      "id": "arps",
                      "title": "Arps parameters",
                      "description": "Arps segments per well, design and stream, with EUR per well",
                      "tables": [
                        {
                          "table": "arps"
                        },
                        {
                          "table": "eur"
                        },
                        {
                          "table": "wells"
                        }
                      ],
                      "available": true,
                      "reason": null,
                      "media_type": "application/zip",
                      "contents": "tables"
                    },
                    {
                      "id": "aries",
                      "title": "ARIES",
                      "description": "One ARIES import text file: 12 monthly volumes per well and design, then declines",
                      "tables": [],
                      "available": true,
                      "reason": null,
                      "media_type": "application/zip",
                      "contents": "text"
                    },
                    {
                      "id": "combocurve",
                      "title": "ComboCurve",
                      "description": "Well header and forecast parameters CSVs, with an EUR check file",
                      "tables": [
                        {
                          "table": "combocurve_wells"
                        },
                        {
                          "table": "combocurve_forecast"
                        }
                      ],
                      "available": true,
                      "reason": null,
                      "media_type": "application/zip",
                      "contents": "tables"
                    },
                    {
                      "id": "valnav",
                      "title": "Val Nav",
                      "description": "Decline CSV by well, reserves category and product, for a Val Nav database in imperial units, with an EUR check file",
                      "tables": [
                        {
                          "table": "valnav_decline"
                        }
                      ],
                      "available": true,
                      "reason": null,
                      "media_type": "application/zip",
                      "contents": "tables"
                    },
                    {
                      "id": "eur",
                      "title": "EUR summary",
                      "description": "EUR per well and design",
                      "tables": [
                        {
                          "table": "eur"
                        },
                        {
                          "table": "wells"
                        }
                      ],
                      "available": true,
                      "reason": null,
                      "media_type": "application/zip",
                      "contents": "tables"
                    },
                    {
                      "id": "drivers",
                      "title": "Forecast drivers",
                      "description": "How much each model input adds to each forecast (SHAP values)",
                      "tables": [
                        {
                          "table": "shap"
                        },
                        {
                          "table": "wells"
                        }
                      ],
                      "available": true,
                      "reason": null,
                      "media_type": "application/zip",
                      "contents": "tables"
                    },
                    {
                      "id": "economics",
                      "title": "Economics summary",
                      "description": "NPV, capex, IRR and payback per well, pad and plan",
                      "tables": [
                        {
                          "table": "economics"
                        },
                        {
                          "table": "wells"
                        }
                      ],
                      "available": true,
                      "reason": null,
                      "media_type": "application/zip",
                      "contents": "tables"
                    }
                  ],
                  "default_preset": "engineer",
                  "p_levels": {
                    "available": [
                      "P50"
                    ],
                    "default": [
                      "P50"
                    ],
                    "reason": "This plan was made without bands, so P10 and P90 rows can't be exported",
                    "convention": "P10 is the low curve and P90 the high one, as Novi labels them; SPE PRMS uses the reverse (P90 is its low, proved case)"
                  },
                  "limits": {
                    "ttl_hours": 24,
                    "max_bytes": 2000000000,
                    "max_queued": 20,
                    "max_queued_per_plan": 3,
                    "max_source_wells": 500,
                    "max_source_wells_by_designs": [
                      500,
                      250,
                      166,
                      125,
                      100,
                      83,
                      71,
                      62,
                      55,
                      50
                    ],
                    "eviction": "oldest_first",
                    "queue_counts": "queued_or_running"
                  },
                  "callbacks": {
                    "enabled": false,
                    "hosts": [],
                    "signed": false,
                    "reason": "Callbacks are off on this server: it allows no callback hosts yet; ask your Novi admin to allow your receiver's host.",
                    "events": [
                      "export.done",
                      "export.failed"
                    ],
                    "signature_header": null,
                    "schemes": [
                      "https"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "parameters": []
    },
    "/exports": {
      "post": {
        "operationId": "createExport",
        "tags": [
          "Exports"
        ],
        "summary": "Start an export",
        "description": "Queues an export of a done plan's tables as one zip and answers 202 with the export and its `Location`. GET /exports/{id}?wait=25 until `status` is `done` (each answer waits for the status to change), then download `file.url`.\n\n**What you send.** `source` names a done plan (`source.plan`), wells to forecast first (`source.wells`) or a comparison (`source.comparison`).\n\n- `preset` (from GET /export-formats) or `tables` with their options: one or neither (the plan's default preset), not both.\n- `wells` and `designs` (indexes into the plan) and `streams` narrow every table.\n- On a plan (or source wells) made with scenarios, `scenario` exports one scenario's wells; wells.csv and Parquet `wells` then add a `scenario` column, last, whatever columns are chosen.\n- On a plan made with `bands: true`, `p_levels` with P10 and P90 adds their rows after each P50 in the monthly, eur and arps tables (P10 is the low curve), and `band_eur: true` runs each band to its own EUR. Default P50 alone.\n\n**What you get.** One CSV per table and, by default, Parquet for fixed-schema tables with Snowflake and Databricks load scripts. The worker fits an `arps` table first (`progress.step` `arps`); the fits stay with the plan for the next export with the same Arps settings.\n\n**Reuse and retries.** The same request for the same plan returns the existing export with `reused: true`: 202 while it is queued or running, 200 once it is done.\n\nAn `Idempotency-Key` retry returns the first request's export as its response did (`reused` only if that had it), even once it failed, was cancelled or expired: it never starts a second one.\n\n**Queue and files.** Small exports (up to 200,000 estimated rows by default) start at once, two at a time; larger ones run one at a time in order, with their `queue_position`.\n\n- Each model set holds up to 20 exports queued or running, and 3 per plan; 409 past either. GET /export-formats `limits` has this server's.\n- An export keeps its plan from this call until its file is written, so deleting the plan or its eviction doesn't stop it.\n- Files are kept 24 hours by default, and the oldest go first past the server's byte budget; the export then reads `expired`.\n- With a state store, any server task answers GET (with `wait`), the download and DELETE for another task's export, and the list for the model set named (send `model_set` for a set other than the default).\n- With the keys in Redis, an `Idempotency-Key` retry on another task replays the first export. An export whose task stopped before it finished reads `error`.\n\n**Errors.** 409 for a table that needs EUR on a plan made without `eur: true`; 503 for an `arps` table the worker can't fit.\n\n- 400: wells that span scenarios with Plan total rows (`forecast`, or `monthly` with `totals`); it says to send `scenario`, or to leave forecast out and set monthly totals false (a preset: only `scenario`).\n- 400: wells that span scenarios in ComboCurve, Val Nav or ARIES files, which carry no scenario; it says to send `scenario`.\n\n**ARIES.** `preset: \"aries\"` writes one ARIES economics import file, `<plan name>.txt` (else aries.txt), in the layout Novi's earlier Forecast Engine writes. Each well name (or id) heads its wells, then a block per design and P-level: START (the well's TIL month, else the plan's start day), the first 12 monthly volumes, 12-month hyperbolic refits and the terminal decline to the scope's EUR years. The worker writes the blocks (`progress.step` `writing`), sorted by name, by code point.\n\n- Options go in `aries`. With compat `fe` the export fails where the earlier writer fails, and a plan, design or well name holding a lone surrogate (which UTF-8 can't encode) fails it with a 409 error naming it; compat `fixed` writes U+FFFD there and sorts by the text it writes.\n- P-levels follow `p_levels`: P50 unless asked, where the earlier layout writes every level present.\n- One set of EUR settings per job: a scope whose wells differ in any of them is a 400 naming `wells`; a scope with its own writes those, not the plan's.\n- 400s: a well name with nothing visible once cleaned, `streams` narrower than the plan's (all three, or those its set serves), and `parquet: true`: ARIES writes every stream, as one text file.\n- Needs a plan made with `eur: true` (409 without); 503 when the worker can't write ARIES (its startup check failed). Unavailable on a set serving neither oil nor gas.\n- manifest.json `aries.notes` says what was left out and why (a failed forecast, a block without the major stream), which wells share a header and which designs would share a qualifier. An export that leaves out everything fails (409 in its error).\n\n**Val Nav and ComboCurve.** Each curve's rows keep its Arps fit through the forecast's last IP day, then follow the plan's EUR decline, so the curve totals the plan's EUR in the tool, with `eur_check.csv`, manifest.json and README.txt beside. The worker fits each curve first (`progress.step` `arps`) with reconcile forward and the plan's b bounds, kept with the plan as an arps table's fits are. GET /export-formats describes every column; manifest.json keys here sit under `valnav` or `combocurve`.\n\n- Needs a plan made with EUR (409) and the worker's Arps fit with reconcile forward (503; GET /export-formats then lists the preset and fitted table unavailable, with that `reason`). `combocurve_wells` alone needs neither.\n- One design per fitted file (a 400 naming `designs`), and one well per Well ID: two wells with one Well ID, or a Well ID with no visible character, are a 400 naming them.\n- GET /export-formats?plan lists the preset unavailable for a plan with more than one design or two wells of one Well ID under the default identity, and the tables available: `designs` and `wells` scope them.\n- `identity` sets the Well ID (`well_id`: the well's name, else its plan label, its id, or its `well_uid`, which keeps two plans' same-named wells apart) and the start date (`til`, or one date).\n- Well IDs and Rescat are written raw: control characters as spaces, CSV quoting.\n- A curve without a plan EUR (P10 and P90 without `band_eur`, water without `eur_water`), whose EUR has no decline fit, or that no Val Nav template brings to it keeps its fit, its reason in `eur_check.csv` `note` and manifest.json `kept_as_fitted`.\n- `eur_check.csv` has each curve's plan EUR, Arps EUR and the tool's EUR of its rows (`tool_eur`), then `max_cum_gap_pct` and `max_cum_gap_month`: over the model's months, the signed largest gap of the rows' cumulative to the forecast's at day 30 × m, and that m.\n  - The rows' cumulative is as Val Nav reads them; for ComboCurve, integrated as `arps_eur`, not ComboCurve's daily sum.\n  - m runs from 1 to the last IP day / 30, rounded down, within the rows. Months where the forecast's cumulative is 0 or missing are left out; both are blank when none is left. manifest.json `eur_check.streams` has each stream's largest.\n\n**Val Nav.** `preset: \"valnav\"`, or `tables: [{\"table\": \"valnav_decline\"}]`, writes `valnav_decline.csv` in the layout Val Nav exports (no public Val Nav import specification exists). Load it into a Val Nav database in imperial units, then compare each curve's EUR with `eur_check.csv`. It has no unit row: rates per day (bbl/d, Mcf/d raw gas), declines nominal in percent per 365.2425-day year.\n\n- After the fit, the rows follow Novi's EUR decline from the fit's rate on the last IP day: one hyperbolic at its b down to the terminal decline, then the tail. With `segments` 2 the second fitted hyperbolic runs on to the tail, at the decline that totals the EUR.\n- `eur_check.csv` `template` and manifest.json `valnav.templates` name each curve's layout: TwoSegmentHyperbolic (one hyperbolic and the tail), SingleSegment (one switching on or after the EUR day), ThreeSegment (two hyperbolics), and TwoSegmentWithRampUp or ThreeSegmentWithRampUp with a ramp.\n- manifest.json `valnav.warnings`: `tail_below_terminal`, where the fit's last-IP-day rate is too low for the terminal decline and every later decline is scaled down by one factor; `tail_bend`, a cumulative more than 10% from the plan's EUR decline at year 5, 10, 20 or 30.\n- It also warns of a ramp with no tail (no template names one) and counts UWIs and Rescats starting with `=`, `+`, `-` or `@`. A curve without a fit is left out, in `valnav.skipped`.\n- `eur_check.csv` adds `tool_vs_forecast_pct` and `tail_bend_pct`.\n- Rescat is `identity.reserves_category` (PUD by default). P50 alone by default: P10 and P90 need `reserves_categories` with a category for each level sent, every level its own (400 otherwise).\n\n**ComboCurve.** `preset: \"combocurve\"` writes `combocurve_wells.csv`, a well header file, and `combocurve_forecast.csv`, forecast parameters with a row per Arps segment; tables `combocurve_wells` and `combocurve_forecast` write them alone. Columns follow ComboCurve's import article and API documentation. Its `segments` (default 2) and `ramp` (default false) are the arps table's.\n\n- After the fit, the rows follow the plan's EUR decline (`eur.arps`: its hyperbolic, then the terminal decline), scaled so ComboCurve's daily sum of the curve's rows totals the plan's EUR, so the rate steps at the last IP day (manifest.json `combocurve.curve`).\n- The tail starts from the fit's cumulative at that day, so its gap to the plan's EUR curve past it follows the fit's own miss there.\n- ComboCurve sums each day's start rate where Novi integrates, so its daily sums read slightly above Novi's volumes; `tool_eur` is that sum.\n- Di Eff-Sec is secant effective, in percent per 365.25-day year, and each segment runs from its Start Date to its End Date inclusive, the next starting the day after.\n- P-levels are series named by exceedance, as ComboCurve names them: Novi's P10 (low) as P90, Novi's P90 (high) as P10, P50 as best. Each is that level's own Arps fit and, with `band_eur`, EUR decline, with its own `eur_check.csv` rows.\n- 400s naming the fix: `identity.reserves_category` (ComboCurve's files carry none), `columns` on either table, a `valnav_decline` table beside either (each writes its own `eur_check.csv`: make two exports), and `combocurve` with other presets or tables.\n- manifest.json `combocurve.formula_keys` counts the IDs starting with `=`, `+`, `-` or `@`: `wells` in the well header, `curves` in the forecast file. A Well Name or Target Formation starting with `=`, `+`, `-`, `@`, a tab or a carriage return gets a leading `'`.\n\n**ComboCurve's two passes.** ComboCurve keys forecast parameters on INPT ID, which it creates with each well. Load `combocurve_wells.csv` as a well header import, add the wells to a forecast, and export the project's well list (Chosen ID, INPT ID). Then send the same request with `combocurve: {\"inpt_ids\": {\"<Well ID>\": \"<INPT ID>\"}}` and import that export's `combocurve_forecast.csv`. Without the map, INPT ID holds the Well ID, and manifest.json `combocurve.inpt_ids` counts the wells without one.\n\n**SHAP.** The `shap` table writes each P50 forecast's SHAP values, a row per well, design, stream, ip day and feature; `shap_value` and `expected_value` are unrounded, in the stream's unit (bbl for oil and water, mcf for gas). Formation's one-hot columns are summed into `novi_formation`, and zero contributions are left out. `p_levels` adds nothing to it.\n\n- The worker explains every forecast first (`progress.step` `explain`), two at a time, so a call on the same model waits behind at most two. A plan well already explained by GET .../explanations is reused; the export keeps nothing on the plan.\n- `ip_days` `all` (default) or `last`; `top` (1 to 50) keeps each row group's largest features and sums the rest into `(other)`, as GET .../explanations' `top` does.\n- A forecast or stream without an explanation gets an error row, counted in manifest.json `shap`; an export with none explained fails with code internal and details.worker forecast.\n- At most 500 forecasts (scoped wells × designs) per export, checked before it queues: past it, a 400 on the table's `table` with `details.max` and `details.count`; scope it with `wells` or `designs`.\n\n**Condensate.** Where the model set labels its oil slot condensate (`stream_labels`, GET /model-sets), or a Legacy Forecast is of condensate, oil is condensate in every file under oil's names (`oil_bbl`, ComboCurve's `oil`, Val Nav's `OIL`); ARIES writes `CND` (B/M), `aries.major_stream` `oil`. Economics prices it at the oil price and differential. manifest.json `source.stream_labels` holds the labels and README.txt says oil = condensate; other exports have neither.\n\n**Wells instead of a plan.** `source.wells` takes wells as POST /plans does, up to `limits.max_source_wells` forecasts (wells × designs), 500 by default; GET /export-formats `limits` reports this server's value and, in `max_source_wells_by_designs`, the most wells per design count. It forecasts them in a plan of its own (unlisted, 404 by id) while `progress.step` is `forecast`, then writes the zip.\n\n- Labels and design names starting with `=`, `+`, `-`, `@`, a tab or a carriage return get a leading `'`; a plan's design names are written as they are.\n- The same wells, labels, designs and settings return the existing export.\n- Each model set forecasts up to 4 exports' wells at once, counting a cancelled export's until its forecast stops; 409 past it.\n\n**A comparison.** `source.comparison` takes a POST /comparisons body without its pricing fields or `wells` (ExportComparisonSource) and writes that route's answer as tables, as Parquet too unless `parquet: false`. delta is b − a and delta_pct (b − a) / a × 100.\n\n- comparison_totals.csv, a row per total: metric, unit, ip_day, horizon_years (on the rows `horizon` adds), a, b, delta, delta_pct, a_wells, b_wells.\n- comparison_spread.csv, a row per side and statistic of the per-well distribution: metric, unit, ip_day, side (a, b, delta or delta_pct), statistic, value; delta rows cover mean and q50.\n- With `group_by`, comparison_groups.csv: group_by and group_key, then the spread's columns.\n- With `include` curves, comparison_curves.csv: side, stream, unit, ip_day, cum, rate, and p10 and p90 with bands. With `align` calendar, comparison_calendar.csv: the same by month_start.\n- With `include` wells, comparison_wells.csv, every pair by a_index: metric, unit, ip_day, a_index, b_index, label, b_label, a, b, delta, delta_pct, band_position.\n- manifest.json `comparison` holds each side as POST /comparisons echoes it and the warnings; with pairing, the pairs (method, a_only and b_only with counts), the per-well summary and `include` inputs' input changes. README.txt says it in words.\n- A text cell (a label, or a formation or scenario in group_key) starting with `=`, `+`, `-`, `@`, a tab or a carriage return gets a leading `'`.\n- A side that is missing, running, failed or on another model set, and any other 400 the body gets, answers as POST /comparisons does, `field` under `source.comparison`.\n- The tables are fixed: `preset`, `tables`, `wells`, `designs`, `scenario`, `streams`, `p_levels`, `aries`, `flags`, `identity` and `source.comparison.wells` are a 400, sent or null, as is a `source.comparison` that isn't an object.\n- The same comparison of the same plans (defaults filled in) returns the existing export. It counts against each side's plan's queue limit, and GET /exports?plan= lists it under either.\n- Its `source` is `kind: comparison`, `plan` null, `comparison` naming both sides. The file is comparison-export-<date>.zip unless `name` is sent.\n\n**A Legacy Forecast.** `source.plan` takes a Legacy Forecast's id from GET /plans?origin=all, and the same writers write it: its curves and EUR are the run's, with Arps segments fitted here. manifest.json `source` adds `origin` and, on a condensate run, `stream_labels`.\n\n- `streams` defaults to the run's `streams`; a stream it didn't forecast is a 400 naming those it did.\n- The neighbors, calc_features, subsurface, shap and economics tables, and the plan_tables, drivers, economics and aries presets, are a 409 with `details.reason` `fe_plan_unsupported`.\n- `identity.well_id` defaults to `id`, the run's unique well key, the same in every export of the run, so same-named wells export; names stay in Well Name and eur_check.csv's `well`. With `\"name\"`, two wells of one name are a 400 naming both.\n- ComboCurve's files and the monthly cumulatives at each 30-day IP day for P50, P10 and P90 of a run with bands, in one call (monthly.csv's at month m is the run's at IP day 30 × m):\n  - `{\"source\": {\"plan\": \"<id>\"}, \"tables\": [{\"table\": \"combocurve_wells\"}, {\"table\": \"combocurve_forecast\"}, {\"table\": \"monthly\", \"horizon\": \"forecast\", \"values\": [\"cumulative\"], \"totals\": false}], \"p_levels\": [\"P50\", \"P10\", \"P90\"], \"parquet\": false}`\n\n**Callbacks.** With `callback_url`, the server POSTs `{\"type\": \"export.done\" | \"export.failed\", \"export\": <the export, as GET /exports/{id} returns it, less callbacks>}` once the export is done or fails (not when it is cancelled).\n\n- Only to hosts the server allows (GET /export-formats `callbacks`; else a 400 on `callback_url`), at public https addresses.\n- Up to 5 URLs per export: the same request with another `callback_url` adds it, and sends it at once when the export is already done.\n- 3 retries, after 2 s, 15 s and 60 s; each attempt, DNS lookup included, has 10 s. Any 2xx is delivered; `callbacks` on the export shows each delivery.\n- Verify `X-Export-Signature` when `callbacks.signed`: `t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<body>\">` with the server's shared secret. Refuse a `t` more than 5 minutes from your clock.\n- Dedupe on `X-Export-Delivery`, one id per export and URL that every retry repeats; `X-Export-Id` and `X-Export-Event` come with it.\n\nA receiver should answer 2xx quickly, then download the file from `export.file.url`: the payload never inlines it.\n\n**Tenant.** Exports belong to the request's tenant: lists hold only its exports, and another tenant's export is a 404 to read, download or delete. A signed-in user's tenant is their customer; a configured user's, the server's default tenant.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "The plan or wells, the preset or tables, and a callback URL.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExportRequest"
              },
              "example": {
                "source": {
                  "plan": "5a0806e5-b6f6-4849-82e3-16ad1d013136"
                },
                "preset": "engineer",
                "name": "Section 36 infill",
                "parquet": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The identical export, already done (reused: true).",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportJob"
                },
                "examples": {
                  "reused": {
                    "summary": "Reused, already done",
                    "value": {
                      "id": "8b8369bd-2c32-4213-8261-f8666e94598c",
                      "status": "done",
                      "created_at": "2026-10-18T03:49:05.135Z",
                      "started_at": "2026-10-18T03:49:05.135Z",
                      "finished_at": "2026-10-18T03:49:05.324Z",
                      "seconds": 0.189,
                      "source": {
                        "kind": "plan",
                        "plan": "5a0806e5-b6f6-4849-82e3-16ad1d013136",
                        "name": "Section 36 infill",
                        "wells": 2,
                        "designs": 2
                      },
                      "name": "Section 36 infill",
                      "preset": "engineer",
                      "tables": [
                        {
                          "table": "monthly",
                          "horizon": "eur",
                          "values": [
                            "volume",
                            "cumulative"
                          ],
                          "totals": true
                        },
                        {
                          "table": "eur"
                        },
                        {
                          "table": "wells"
                        },
                        {
                          "table": "designs"
                        }
                      ],
                      "wells": null,
                      "designs": null,
                      "streams": [
                        "oil",
                        "gas",
                        "water"
                      ],
                      "parquet": true,
                      "queue_position": null,
                      "progress": {
                        "step": "done",
                        "fraction": 1,
                        "rows": 3658,
                        "rows_total": 3658,
                        "bytes": 400000
                      },
                      "file": {
                        "name": "Section 36 infill.zip",
                        "bytes": 400000,
                        "sha256": "9a45493b5976c7af3afd4ff876eee1321a58894d4677e47162254f54d6167a7a",
                        "url": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c/file",
                        "expires_at": "2026-10-19T03:49:05.324Z",
                        "entries": [
                          {
                            "name": "monthly.csv",
                            "rows": 3648,
                            "bytes": 309308
                          },
                          {
                            "name": "eur.csv",
                            "rows": 4,
                            "bytes": 1274
                          },
                          {
                            "name": "wells.csv",
                            "rows": 2,
                            "bytes": 478
                          },
                          {
                            "name": "designs.csv",
                            "rows": 4,
                            "bytes": 298
                          },
                          {
                            "name": "parquet/monthly.parquet",
                            "rows": 3648,
                            "bytes": 72000
                          },
                          {
                            "name": "parquet/eur.parquet",
                            "rows": 4,
                            "bytes": 3400
                          },
                          {
                            "name": "parquet/wells.parquet",
                            "rows": 2,
                            "bytes": 2800
                          },
                          {
                            "name": "parquet/designs.parquet",
                            "rows": 4,
                            "bytes": 2600
                          }
                        ]
                      },
                      "error": null,
                      "callbacks": [],
                      "links": {
                        "self": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c",
                        "file": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c/file"
                      },
                      "reused": true
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "The export, queued or running (or the identical one already queued or running, with reused: true; or, replaying an Idempotency-Key, as it is now).",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportJob"
                },
                "examples": {
                  "started": {
                    "summary": "Started",
                    "value": {
                      "id": "8b8369bd-2c32-4213-8261-f8666e94598c",
                      "status": "running",
                      "created_at": "2026-10-18T03:49:05.135Z",
                      "started_at": "2026-10-18T03:49:05.135Z",
                      "finished_at": null,
                      "seconds": 0,
                      "source": {
                        "kind": "plan",
                        "plan": "5a0806e5-b6f6-4849-82e3-16ad1d013136",
                        "name": "Section 36 infill",
                        "wells": 2,
                        "designs": 2
                      },
                      "name": "Section 36 infill",
                      "preset": "engineer",
                      "tables": [
                        {
                          "table": "monthly",
                          "horizon": "eur",
                          "values": [
                            "volume",
                            "cumulative"
                          ],
                          "totals": true
                        },
                        {
                          "table": "eur"
                        },
                        {
                          "table": "wells"
                        },
                        {
                          "table": "designs"
                        }
                      ],
                      "wells": null,
                      "designs": null,
                      "streams": [
                        "oil",
                        "gas",
                        "water"
                      ],
                      "parquet": true,
                      "queue_position": null,
                      "progress": {
                        "step": "writing",
                        "fraction": 0,
                        "rows": 0,
                        "rows_total": 3658,
                        "bytes": 0
                      },
                      "file": null,
                      "error": null,
                      "callbacks": [],
                      "links": {
                        "self": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c",
                        "file": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c/file"
                      }
                    }
                  },
                  "wells": {
                    "summary": "From a drawn well, forecasting",
                    "value": {
                      "id": "22bf720c-916c-4e64-a62f-603a2521322d",
                      "status": "running",
                      "created_at": "2026-10-18T03:49:05.355Z",
                      "started_at": "2026-10-18T03:49:05.355Z",
                      "finished_at": null,
                      "seconds": 0,
                      "source": {
                        "kind": "drawn",
                        "plan": null,
                        "name": null,
                        "wells": 1,
                        "designs": 1
                      },
                      "name": null,
                      "preset": "engineer",
                      "tables": [
                        {
                          "table": "monthly",
                          "horizon": "eur",
                          "values": [
                            "volume",
                            "cumulative"
                          ],
                          "totals": false
                        },
                        {
                          "table": "eur"
                        },
                        {
                          "table": "wells"
                        },
                        {
                          "table": "designs"
                        }
                      ],
                      "wells": null,
                      "designs": null,
                      "streams": [
                        "oil",
                        "gas",
                        "water"
                      ],
                      "parquet": true,
                      "queue_position": null,
                      "progress": {
                        "step": "forecast",
                        "fraction": 0,
                        "rows": 0,
                        "rows_total": 611,
                        "bytes": 0
                      },
                      "file": null,
                      "error": null,
                      "callbacks": [],
                      "links": {
                        "self": "/api/v1/exports/22bf720c-916c-4e64-a62f-603a2521322d",
                        "file": "/api/v1/exports/22bf720c-916c-4e64-a62f-603a2521322d/file"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "A conflict with the plan, the queue, the callbacks or the Idempotency-Key.\n\n- The plan is running or failed, or a table needs EUR the plan or wells don't have.\n- The model set or plan has as many exports queued or running as it takes, or the model set is forecasting as many exports' wells as it takes.\n- The export has 5 callbacks.\n- The Idempotency-Key was used with a different body; or, with Redis, the first request with this Idempotency-Key is still being made (after a 30 s wait); retry shortly with the same key.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "conflict",
                    "message": "Plan 5a0806e5-b6f6-4849-82e3-16ad1d013136 already has 3 exports queued or running, the most one plan may; wait for one to finish, or cancel one with DELETE /api/v1/exports/{id}",
                    "details": {
                      "plan": "5a0806e5-b6f6-4849-82e3-16ad1d013136",
                      "limit": 3,
                      "active": 3
                    }
                  },
                  "request_id": "2e7b9c41-6a3d-4f8e-b5c2-9d0a1e4f7b36"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "description": "A model worker or the subsurface grids aren't ready, or, with Redis, the Redis that keeps Idempotency-Key records isn't answering; retry shortly with the same key.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unavailable",
                    "message": "The spacing model worker isn't running; retry shortly, and ask your Novi admin if it persists",
                    "details": {
                      "worker": "spacing"
                    }
                  },
                  "request_id": "0b5e8f2a-7c1d-4e6b-a3f9-5d2c8e4b1a70"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listExports",
        "tags": [
          "Exports"
        ],
        "summary": "List exports",
        "description": "Exports held in the request's model set (see `model_set`), newest first: queued, running, done, and tombstones of failed, cancelled and expired ones until the server's job cap drops them.\n\n**Filters.** `ids` lists only those exports (the app lists the ones its browser created); `plan` and `status` filter.\n\n**Tenant.** Exports belong to the request's tenant: lists hold only its exports, and another tenant's export is a 404 to read, download or delete. A signed-in user's tenant is their customer; a configured user's, the server's default tenant.",
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "description": "Only these exports: up to 100 export ids, comma-separated. Unknown ids are left out.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plan",
            "in": "query",
            "description": "Only exports of this plan id; a comparison export is listed under either side's plan.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Only exports in this status.",
            "schema": {
              "type": "string",
              "enum": [
                "queued",
                "running",
                "done",
                "error",
                "cancelled",
                "expired"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "Exports.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportList"
                },
                "example": {
                  "exports": [
                    {
                      "id": "8b8369bd-2c32-4213-8261-f8666e94598c",
                      "status": "done",
                      "created_at": "2026-10-18T03:49:05.135Z",
                      "started_at": "2026-10-18T03:49:05.135Z",
                      "finished_at": "2026-10-18T03:49:05.324Z",
                      "seconds": 0.189,
                      "source": {
                        "kind": "plan",
                        "plan": "5a0806e5-b6f6-4849-82e3-16ad1d013136",
                        "name": "Section 36 infill",
                        "wells": 2,
                        "designs": 2
                      },
                      "name": "Section 36 infill",
                      "preset": "engineer",
                      "tables": [
                        {
                          "table": "monthly",
                          "horizon": "eur",
                          "values": [
                            "volume",
                            "cumulative"
                          ],
                          "totals": true
                        },
                        {
                          "table": "eur"
                        },
                        {
                          "table": "wells"
                        },
                        {
                          "table": "designs"
                        }
                      ],
                      "wells": null,
                      "designs": null,
                      "streams": [
                        "oil",
                        "gas",
                        "water"
                      ],
                      "parquet": true,
                      "queue_position": null,
                      "progress": {
                        "step": "done",
                        "fraction": 1,
                        "rows": 3658,
                        "rows_total": 3658,
                        "bytes": 400000
                      },
                      "file": {
                        "name": "Section 36 infill.zip",
                        "bytes": 400000,
                        "sha256": "9a45493b5976c7af3afd4ff876eee1321a58894d4677e47162254f54d6167a7a",
                        "url": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c/file",
                        "expires_at": "2026-10-19T03:49:05.324Z",
                        "entries": [
                          {
                            "name": "monthly.csv",
                            "rows": 3648,
                            "bytes": 309308
                          },
                          {
                            "name": "eur.csv",
                            "rows": 4,
                            "bytes": 1274
                          },
                          {
                            "name": "wells.csv",
                            "rows": 2,
                            "bytes": 478
                          },
                          {
                            "name": "designs.csv",
                            "rows": 4,
                            "bytes": 298
                          },
                          {
                            "name": "parquet/monthly.parquet",
                            "rows": 3648,
                            "bytes": 72000
                          },
                          {
                            "name": "parquet/eur.parquet",
                            "rows": 4,
                            "bytes": 3400
                          },
                          {
                            "name": "parquet/wells.parquet",
                            "rows": 2,
                            "bytes": 2800
                          },
                          {
                            "name": "parquet/designs.parquet",
                            "rows": 4,
                            "bytes": 2600
                          }
                        ]
                      },
                      "error": null,
                      "callbacks": [
                        {
                          "url": "https://hooks.example.com/novi/exports",
                          "status": "delivered",
                          "attempts": 1,
                          "last_status": 204,
                          "last_error": null,
                          "delivered_at": "2026-10-18T03:49:05.536Z"
                        }
                      ],
                      "links": {
                        "self": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c",
                        "file": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c/file"
                      }
                    }
                  ],
                  "next_cursor": null
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "parameters": []
    },
    "/exports/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ExportId"
        }
      ],
      "get": {
        "operationId": "getExport",
        "tags": [
          "Exports"
        ],
        "summary": "Get an export",
        "description": "Status, queue position, progress (step, fraction, rows and bytes written) and, once done, the file: name, size, SHA-256, URL, expiry and each entry's rows and bytes.\n\n**Polling.** Queued or running, it answers with `Retry-After: 1`; send `wait` instead of polling.\n\n**Tenant.** Exports belong to the request's tenant: lists hold only its exports, and another tenant's export is a 404 to read, download or delete. A signed-in user's tenant is their customer; a configured user's, the server's default tenant.",
        "parameters": [
          {
            "name": "wait",
            "in": "query",
            "description": "Use this instead of polling: on a queued or running export, the answer is held until its status changes (queued to running, or to done, error or cancelled), or this many seconds pass.\n\nWhole seconds, 1 to 25 (400 otherwise). The answer is what a GET without `wait` would get when the wait ends, `Retry-After` included; a finished job answers at once. A client that disconnects ends the wait.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The export.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportJob"
                },
                "examples": {
                  "queued": {
                    "summary": "Queued",
                    "value": {
                      "id": "8b8369bd-2c32-4213-8261-f8666e94598c",
                      "status": "queued",
                      "created_at": "2026-10-18T03:49:05.135Z",
                      "started_at": null,
                      "finished_at": null,
                      "seconds": null,
                      "source": {
                        "kind": "plan",
                        "plan": "5a0806e5-b6f6-4849-82e3-16ad1d013136",
                        "name": "Section 36 infill",
                        "wells": 2,
                        "designs": 2
                      },
                      "name": "Section 36 infill",
                      "preset": "engineer",
                      "tables": [
                        {
                          "table": "monthly",
                          "horizon": "eur",
                          "values": [
                            "volume",
                            "cumulative"
                          ],
                          "totals": true
                        },
                        {
                          "table": "eur"
                        },
                        {
                          "table": "wells"
                        },
                        {
                          "table": "designs"
                        }
                      ],
                      "wells": null,
                      "designs": null,
                      "streams": [
                        "oil",
                        "gas",
                        "water"
                      ],
                      "parquet": true,
                      "queue_position": 1,
                      "progress": {
                        "step": "queued",
                        "fraction": 0,
                        "rows": 0,
                        "rows_total": 3658,
                        "bytes": 0
                      },
                      "file": null,
                      "error": null,
                      "callbacks": [],
                      "links": {
                        "self": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c",
                        "file": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c/file"
                      }
                    }
                  },
                  "running": {
                    "summary": "Running",
                    "value": {
                      "id": "8b8369bd-2c32-4213-8261-f8666e94598c",
                      "status": "running",
                      "created_at": "2026-10-18T03:49:05.135Z",
                      "started_at": "2026-10-18T03:49:05.135Z",
                      "finished_at": null,
                      "seconds": 0,
                      "source": {
                        "kind": "plan",
                        "plan": "5a0806e5-b6f6-4849-82e3-16ad1d013136",
                        "name": "Section 36 infill",
                        "wells": 2,
                        "designs": 2
                      },
                      "name": "Section 36 infill",
                      "preset": "engineer",
                      "tables": [
                        {
                          "table": "monthly",
                          "horizon": "eur",
                          "values": [
                            "volume",
                            "cumulative"
                          ],
                          "totals": true
                        },
                        {
                          "table": "eur"
                        },
                        {
                          "table": "wells"
                        },
                        {
                          "table": "designs"
                        }
                      ],
                      "wells": null,
                      "designs": null,
                      "streams": [
                        "oil",
                        "gas",
                        "water"
                      ],
                      "parquet": true,
                      "queue_position": null,
                      "progress": {
                        "step": "writing",
                        "fraction": 0,
                        "rows": 0,
                        "rows_total": 3658,
                        "bytes": 0
                      },
                      "file": null,
                      "error": null,
                      "callbacks": [],
                      "links": {
                        "self": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c",
                        "file": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c/file"
                      }
                    }
                  },
                  "done": {
                    "summary": "Done",
                    "value": {
                      "id": "8b8369bd-2c32-4213-8261-f8666e94598c",
                      "status": "done",
                      "created_at": "2026-10-18T03:49:05.135Z",
                      "started_at": "2026-10-18T03:49:05.135Z",
                      "finished_at": "2026-10-18T03:49:05.324Z",
                      "seconds": 0.189,
                      "source": {
                        "kind": "plan",
                        "plan": "5a0806e5-b6f6-4849-82e3-16ad1d013136",
                        "name": "Section 36 infill",
                        "wells": 2,
                        "designs": 2
                      },
                      "name": "Section 36 infill",
                      "preset": "engineer",
                      "tables": [
                        {
                          "table": "monthly",
                          "horizon": "eur",
                          "values": [
                            "volume",
                            "cumulative"
                          ],
                          "totals": true
                        },
                        {
                          "table": "eur"
                        },
                        {
                          "table": "wells"
                        },
                        {
                          "table": "designs"
                        }
                      ],
                      "wells": null,
                      "designs": null,
                      "streams": [
                        "oil",
                        "gas",
                        "water"
                      ],
                      "parquet": true,
                      "queue_position": null,
                      "progress": {
                        "step": "done",
                        "fraction": 1,
                        "rows": 3658,
                        "rows_total": 3658,
                        "bytes": 400000
                      },
                      "file": {
                        "name": "Section 36 infill.zip",
                        "bytes": 400000,
                        "sha256": "9a45493b5976c7af3afd4ff876eee1321a58894d4677e47162254f54d6167a7a",
                        "url": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c/file",
                        "expires_at": "2026-10-19T03:49:05.324Z",
                        "entries": [
                          {
                            "name": "monthly.csv",
                            "rows": 3648,
                            "bytes": 309308
                          },
                          {
                            "name": "eur.csv",
                            "rows": 4,
                            "bytes": 1274
                          },
                          {
                            "name": "wells.csv",
                            "rows": 2,
                            "bytes": 478
                          },
                          {
                            "name": "designs.csv",
                            "rows": 4,
                            "bytes": 298
                          },
                          {
                            "name": "parquet/monthly.parquet",
                            "rows": 3648,
                            "bytes": 72000
                          },
                          {
                            "name": "parquet/eur.parquet",
                            "rows": 4,
                            "bytes": 3400
                          },
                          {
                            "name": "parquet/wells.parquet",
                            "rows": 2,
                            "bytes": 2800
                          },
                          {
                            "name": "parquet/designs.parquet",
                            "rows": 4,
                            "bytes": 2600
                          }
                        ]
                      },
                      "error": null,
                      "callbacks": [
                        {
                          "url": "https://hooks.example.com/novi/exports",
                          "status": "delivered",
                          "attempts": 1,
                          "last_status": 204,
                          "last_error": null,
                          "delivered_at": "2026-10-18T03:49:05.536Z"
                        }
                      ],
                      "links": {
                        "self": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c",
                        "file": "/api/v1/exports/8b8369bd-2c32-4213-8261-f8666e94598c/file"
                      }
                    }
                  },
                  "aries": {
                    "summary": "ARIES, done",
                    "value": {
                      "id": "2f6c0d1e-7a4b-4c39-9e21-5b8d3a6f0c47",
                      "status": "done",
                      "created_at": "2026-10-18T03:52:11.402Z",
                      "started_at": "2026-10-18T03:52:11.403Z",
                      "finished_at": "2026-10-18T03:52:12.118Z",
                      "seconds": 0.715,
                      "source": {
                        "kind": "plan",
                        "plan": "5a0806e5-b6f6-4849-82e3-16ad1d013136",
                        "name": "Section 36 infill",
                        "wells": 2,
                        "designs": 2
                      },
                      "name": null,
                      "preset": "aries",
                      "tables": [],
                      "wells": null,
                      "designs": null,
                      "streams": [
                        "oil",
                        "gas",
                        "water"
                      ],
                      "parquet": false,
                      "aries": {
                        "compat": "fixed",
                        "major_stream": "oil",
                        "well_key": "name",
                        "start_date": null,
                        "clean": true
                      },
                      "queue_position": null,
                      "progress": {
                        "step": "done",
                        "fraction": 1,
                        "rows": 212,
                        "rows_total": 212,
                        "bytes": 3712
                      },
                      "file": {
                        "name": "plan-2-wells-aries-2026-10-18.zip",
                        "bytes": 3712,
                        "sha256": "5d2f8a1c0e7b4f3a9c6d2e1b8a7f4c3d0e9b8a7c6d5e4f3a2b1c0d9e8f7a6b5c",
                        "url": "/api/v1/exports/2f6c0d1e-7a4b-4c39-9e21-5b8d3a6f0c47/file",
                        "expires_at": "2026-10-19T03:52:12.118Z",
                        "entries": [
                          {
                            "name": "Section 36 infill.txt",
                            "rows": 212,
                            "bytes": 19142
                          }
                        ]
                      },
                      "error": null,
                      "callbacks": [],
                      "links": {
                        "self": "/api/v1/exports/2f6c0d1e-7a4b-4c39-9e21-5b8d3a6f0c47",
                        "file": "/api/v1/exports/2f6c0d1e-7a4b-4c39-9e21-5b8d3a6f0c47/file"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "delete": {
        "operationId": "deleteExport",
        "tags": [
          "Exports"
        ],
        "summary": "Cancel or remove an export",
        "description": "Cancels a queued or running export, or removes a finished one with its file. `status` is the export's status when the request arrived.\n\n**Cancel or remove.** A cancelled export stops, any partial file is removed, and it reads `cancelled`. A removed one (done, failed, cancelled or expired) is then not found.\n\n**Tenant.** Exports belong to the request's tenant: lists hold only its exports, and another tenant's export is a 404 to read, download or delete. A signed-in user's tenant is their customer; a configured user's, the server's default tenant.",
        "responses": {
          "200": {
            "description": "Cancelled or removed.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedExport"
                },
                "example": {
                  "id": "8b8369bd-2c32-4213-8261-f8666e94598c",
                  "deleted": true,
                  "status": "done"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/exports/{id}/file": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ExportId"
        }
      ],
      "get": {
        "operationId": "downloadExport",
        "tags": [
          "Exports"
        ],
        "summary": "Download an export's zip",
        "description": "A done export's zip, streamed with its `Content-Length`, a strong `ETag` and `Accept-Ranges: bytes`, so a download can resume. HEAD answers the same headers without the body.\n\n**Ranges.** `Range: bytes=a-b`, `a-` or `-n` (the last n bytes) answers 206 with `Content-Range`; a range starting past the end is 416, and several ranges get the whole file. `If-Range` sends the range only for this ETag, else the whole file. `If-None-Match` with the ETag answers 304.\n\n**Another task's file.** GET answers a file another server task wrote with a 307 to a copy in the server's file store, signed for 15 minutes, which takes Range and has its own ETag: follow it without this API's credentials. HEAD and If-None-Match still answer here.\n\n**Errors.** 409 until the export is done (or when it failed or was cancelled), 410 once it expired.\n\n**Tenant.** Exports belong to the request's tenant: lists hold only its exports, and another tenant's export is a 404 to read, download or delete. A signed-in user's tenant is their customer; a configured user's, the server's default tenant.",
        "parameters": [
          {
            "name": "Range",
            "in": "header",
            "description": "One byte range, as bytes=0-1048575, bytes=1048576- or bytes=-1024.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "If-Range",
            "in": "header",
            "description": "The ETag of the copy you have part of: the range is sent only if the file is still that one.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The zip.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/FileETag"
              },
              "Content-Length": {
                "$ref": "#/components/headers/ContentLength"
              },
              "Accept-Ranges": {
                "$ref": "#/components/headers/AcceptRanges"
              },
              "Content-Disposition": {
                "$ref": "#/components/headers/ExportContentDisposition"
              }
            },
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "application/zip",
                  "description": "Zip archive."
                }
              }
            }
          },
          "206": {
            "description": "The requested bytes of the zip.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/FileETag"
              },
              "Content-Range": {
                "$ref": "#/components/headers/ContentRange"
              },
              "Content-Length": {
                "$ref": "#/components/headers/ContentLength"
              },
              "Accept-Ranges": {
                "$ref": "#/components/headers/AcceptRanges"
              },
              "Content-Disposition": {
                "$ref": "#/components/headers/ExportContentDisposition"
              }
            },
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "application/zip",
                  "description": "Part of the zip archive."
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "307": {
            "description": "Another server task wrote the file: download it from `Location`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Location": {
                "description": "The zip in the server's file store, signed for 15 minutes.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The export isn't done yet, or it failed or was cancelled, so it has no file.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "conflict",
                    "message": "Export 8b8369bd-2c32-4213-8261-f8666e94598c is still running; download it once its status is done",
                    "details": {
                      "id": "8b8369bd-2c32-4213-8261-f8666e94598c",
                      "status": "running"
                    }
                  },
                  "request_id": "8c3f1a72-4e9b-4d06-a1f5-6b2e8d7c0a94"
                }
              }
            }
          },
          "410": {
            "$ref": "#/components/responses/Gone"
          },
          "416": {
            "$ref": "#/components/responses/RangeNotSatisfiable"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/export-callbacks/test": {
      "post": {
        "operationId": "testExportCallback",
        "tags": [
          "Exports"
        ],
        "summary": "Send a test callback",
        "description": "POSTs one `{\"type\": \"export.test\", \"sent_at\": <time>}` to `url`, signed and checked as `callback_url` is (the host allowlist, https and public addresses only), with `X-Export-Event: export.test`, and answers with what the receiver did. No retries; up to 10 a minute per server (409 past it). A 200 says the test ran: `ok` says whether the receiver took it.",
        "requestBody": {
          "required": true,
          "description": "The URL to try.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CallbackTestRequest"
              },
              "example": {
                "url": "https://hooks.example.com/novi/exports"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The delivery.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallbackTest"
                },
                "example": {
                  "url": "https://hooks.example.com/novi/exports",
                  "ok": true,
                  "status": 204,
                  "error": null,
                  "ms": 184
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "description": "This server sent as many test callbacks in the last minute as it takes.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "conflict",
                    "message": "This server sends at most 10 test callbacks a minute; retry in a minute",
                    "details": {
                      "limit": 10
                    }
                  },
                  "request_id": "7a2e5c91-0d4b-4f63-8e1a-3b9c6d2f5e08"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/changelog": {
      "get": {
        "operationId": "getChangelog",
        "tags": [
          "Service"
        ],
        "summary": "List releases and what changed",
        "description": "Releases, newest first, as the app's changelog lists them; `since=0.13` gives what changed after v0.13. It changes only with a deploy, so it carries an ETag.\n\n**The answer.** This build's `version` and `api_version`; `unreleased`, what is merged and deployed but not released (the same on every page); then each release's version, git tag, date and entries. An entry has its tag (New, Change, Fix or Remove), its text and `prs`, the pull requests its trailing `(#N)` names, which `text` leaves out.",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "description": "Only releases newer than this version, as `0.13` or `v0.13`.",
            "schema": {
              "type": "string",
              "pattern": "^v?(0|[1-9][0-9]*)\\.(0|0[1-9]|[1-9][0-9])$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Releases per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Releases, newest first.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Changelog"
                },
                "example": {
                  "version": "0.16",
                  "api_version": "1.16.0",
                  "unreleased": [
                    {
                      "tag": "New",
                      "text": "GET /changelog lists what changed in each release, newest first, and what's deployed but not released yet, each change with its pull requests; since=0.13 gives only the releases after v0.13. The API is 1.4.0",
                      "prs": [
                        22
                      ]
                    },
                    {
                      "tag": "New",
                      "text": "The API reference has a Changelog card: this build's version, the API version and the latest release's changes",
                      "prs": [
                        22
                      ]
                    }
                  ],
                  "releases": [
                    {
                      "version": "0.16",
                      "tag": "v0.16",
                      "date": "2026-10-17",
                      "entries": [
                        {
                          "tag": "New",
                          "text": "API 1.3.0: eur and decline on POST /forecasts and POST /plans, plan EUR totals and export columns, POST /declines to fit curves a caller has, and GET /dataset eur",
                          "prs": [
                            21
                          ]
                        }
                      ]
                    }
                  ],
                  "next_cursor": "bzox"
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "description": "This build is missing VERSION or CHANGELOG.md.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unavailable",
                    "message": "This build has no CHANGELOG.md, so it has no changelog to list",
                    "details": {
                      "file": "CHANGELOG.md"
                    }
                  },
                  "request_id": "5d8a3c1e-9f2b-4e7a-b6c4-1a0e9d8f7b23"
                }
              }
            }
          }
        }
      }
    },
    "/conventions": {
      "get": {
        "operationId": "getConventions",
        "tags": [
          "Service"
        ],
        "summary": "Get units and conventions",
        "description": "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.\n\n**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": [
          {
            "name": "include",
            "in": "query",
            "description": "`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.",
            "schema": {
              "type": "string",
              "enum": [
                "decline_profiles"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "Units and conventions.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conventions"
                },
                "examples": {
                  "all": {
                    "summary": "Conventions",
                    "value": {
                      "api_version": "1.16.0",
                      "units": {
                        "oil": "bbl",
                        "gas": "mcf",
                        "water": "bbl",
                        "boe": "BOE",
                        "lateral_length": "ft",
                        "tvd": "ft",
                        "proppant": "lb/ft",
                        "fluid": "bbl/ft",
                        "money": "USD"
                      },
                      "boe": {
                        "gas_mcf_per_bbl": 6,
                        "label": "BOE (6:1)"
                      },
                      "p_levels": {
                        "low": "P10",
                        "high": "P90",
                        "convention": "P10 is the low curve and P90 the high one, as Novi labels them; SPE PRMS uses the reverse (P90 is its low, proved case)"
                      },
                      "sections": [
                        {
                          "id": "units",
                          "title": "Units",
                          "markdown": "- Oil and water are in bbl (barrels). Gas is in mcf (thousand cubic feet). Field names and descriptions carry the unit.\n- Volumes are cumulative at each ip_day, the days since first production. Rates are daily averages, in bbl/d and mcf/d.\n- Lengths and depths are in ft. Completions are fluid in bbl per lateral ft and proppant in lb per lateral ft.\n- Points are [lng, lat] in WGS 84 degrees.\n- To compare wells of different lengths, divide by the lateral length in ft and multiply by 1,000: \"per 1,000 ft\".\n- Keep the unit when you shorten a number: Mbbl is a thousand bbl, MMcf a thousand mcf."
                        },
                        {
                          "id": "boe",
                          "title": "BOE",
                          "markdown": "- BOE (barrels of oil equivalent) is oil plus gas at 6 mcf per bbl: BOE = oil bbl + gas mcf / 6.\n- Label it \"BOE (6:1)\" so the reader knows the ratio.\n- BOE needs both oil and gas when the forecast carries both: when either is missing, BOE is missing too. A forecast that carries only one of them, because its model set or source has no other, has BOE from that stream alone (oil bbl, or gas mcf / 6).\n- Water is not part of BOE."
                        },
                        {
                          "id": "p-levels",
                          "title": "P10, P50 and P90",
                          "markdown": "- P50 is the point forecast; label numbers from a forecast without bands \"P50\". Novi's P10 is the low curve and P90 the high curve.\n- That is the reverse of SPE PRMS. In the API's words: P10 is the low curve and P90 the high one, as Novi labels them; SPE PRMS uses the reverse (P90 is its low, proved case).\n- Whenever you show P10 or P90, say which convention it is, as \"Novi convention: P10 low, P90 high\".\n- P10 and P90 bound one well's forecast. The spread across a plan's wells is quantiles (q10, q50, q90), which are not P-levels; call them well quantiles."
                        },
                        {
                          "id": "eur",
                          "title": "EUR",
                          "markdown": "- EUR (estimated ultimate recovery) is the forecast extended by a decline-curve fit to the EUR day. It is not a model output.\n- EUR covers oil and gas; water has one only with eur_water: true, and BOE never reads it.\n- It is opt-in: eur: true on a forecast, a plan or a wells export.\n- Quote the settings from GET /dataset eur: defaults (eur_years, terminal_decline, b_min, b_max) and bounds. Do not state them from memory. Call the method a decline-curve fit to the EUR day rather than quoting eur.method.\n- A request's decline settings override the defaults and come back in its decline echo; quote those when a request set them, or each well's inputs.resolved.decline when the echo says per_well.\n- When GET /dataset eur.available is false, this server has no EUR. Say so instead of estimating one."
                        },
                        {
                          "id": "bands",
                          "title": "P10/P90 bands",
                          "markdown": "- Bands are a low (P10) and a high (P90) cumulative curve around each stream's forecast.\n- On the production models they are split conformal prediction bands, fit once per model and stored beside it, computed in the same model call as the forecast.\n- They are opt-in: bands: true on a forecast or plan. band_eur: true also fits each band's EUR.\n- GET /dataset bands says whether this server has them, for which streams, and the reason when not. On the production models, call them split conformal bands rather than quoting bands.method.\n- When bands are unavailable, or a stream has none, show P50 alone and say \"P50 only\". Never draw or estimate a band yourself.\n- Plan totals add the wells' P10 curves, and their P90 curves. A sum of P10s is not the plan's own P10."
                        },
                        {
                          "id": "input-checks",
                          "title": "Input checks",
                          "markdown": "- Every forecast design carries checks: the inputs the model rarely or never saw in training, checked on the oil model's rows against its training statistics.\n- out_of_range lists numeric inputs more than 5% of their training range (99th minus 1st percentile) below the 1st or above the 99th percentile of training, each with its value and that training range.\n- context lists neighbors' production outside the 1st to 99th percentile of training, each with its side: it describes the parent depletion near the well, which moves little with completions but does with where the lateral is drawn. above means more parent depletion nearby than nearly all training wells, below less: say so, not that an input is unusual. It does not set flagged. Tool rows give it as counts by side (context: {above, below}), and totals count the wells with any (context, or wells_context on plan totals), each only when there are any.\n- missing lists inputs left blank that are blank in under 5% of training rows. unknown_formation names a target formation the model has no training wells in.\n- When flagged is true, say how many inputs are outside the training data, name each with its value and range, and say the forecast is less certain.\n- Show the flag beside any number you quote from a well whose checks are flagged, and beside any plan total whose wells_flagged is above 0, saying how many wells it covers.\n- When checks.available is false, say the inputs were not checked, and why."
                        },
                        {
                          "id": "area-files",
                          "title": "Shapefiles and other area files",
                          "markdown": "- An area file is a zipped shapefile, GeoJSON, KML or KMZ. In a zip the .shp is enough: the .dbf adds the attributes and the .prj the coordinate system. Only polygons are read. A zip's first polygon layer is used, and a record of another shape is skipped.\n- The coordinate system is the one sent as `crs`, else the file's own: its .prj, the one a GeoJSON file names, or WGS 84 for KML and for GeoJSON in degrees that names none. Otherwise, or when the API does not read the file's system, it is detected: the first known system that places the coordinates on the dataset. The answer names the system and whether the request, the file or detection gave it. When detection gave it and other systems would also fit but place the areas elsewhere, the answer lists them with a warning. When detection finds none, coordinates in degrees are read as WGS 84 with a warning, and others are refused. Areas come back in WGS 84 longitude and latitude.\n- One record is one area, with its attributes: a shapefile record, a GeoJSON feature or a KML placemark. An area keeps the file's first 50 attributes, plus any that name it, each text value cut at 200 characters. A record is skipped when it has no area, is not a polygon, is damaged, has coordinates off the globe, or its .dbf row is marked deleted. The answer lists the first 100 skipped records with the reason and counts the rest. Shapefile records past the .dbf's last row are not read, with a warning.\n- A client may name the attribute field that names the areas (`name_field`), or several (`name_fields`, at most 5; send one or the other), whose values are joined in order by `name_separator`, one space by default, with blanks left out. With none named, the API picks a field with a usual name for names, such as a name or lease name field, that at least 90% of records fill, else the first text field whose filled values all differ. An area with no name value is \"Area N\", N being its record's number counting from one. Names need not differ, except in a file read as pads: there a pad with no name value is \"Pad N\", and a pad whose name repeats one kept before it is left out.\n- A hole is not part of its area. Acres leave it out, and wells laid on the area's whole shape stay out of it. A hole that lies wholly outside its outline is read as a part of its own, and one that crosses its outline or is as large is left out, each with a warning. Holes are checked in file order within a fixed amount of work per request. Past it, a plain read takes each later hole as the file gives it, with no warning; filling many areas and reading pads leave out an area whose holes can't all be checked. The single outline each area also carries, for clients that take one ring, is its largest part without its holes, simplified to at most 500 corners, and none when that ring can't be filled.\n- An area with several parts is one area, with one name and its parts' acres added. Wells laid on its whole shape fill every part.\n- An area whose bounding box misses the dataset's is still read, and marked as outside the dataset. Filling many areas skips it, and reading pads leaves it out.\n- Filling many areas at once:\n  - Areas, or parts of areas, that share an edge are laid as one piece of land: their edges run within 1 ft of each other along an unbroken 100 ft or more, or they overlap. A shared corner, or edges that touch only here and there, do not join them.\n  - A well may cross the line between joined areas. It never leaves the piece, and never runs through a hole that no other area covers. Land that two areas both cover is laid once.\n  - Setbacks (`setback_ft`, `setback_end_ft`) hold at the piece's outer edges and holes, not at the lines between its areas. Where two areas overlap, an edge that runs inside the other area still keeps its setbacks.\n  - Along each line, every unbroken stretch of land, less its setbacks, takes as many wells of the full `lateral_length_ft` as fit. When the land left over is at least `min_lateral_ft`, the stretch takes one more well, and all its wells are of equal length. Otherwise the full-length wells are centred on the stretch. A stretch shorter than the minimum takes no well.\n  - `lateral_length_ft` is required, from 1,000 to 30,000 ft. `min_lateral_ft` is 1,000 ft up to that length; left out, it is 85% of the length, at least 1,000 ft.\n  - Each piece's wells run along its largest part's longest edge, or square to that edge when the piece is longer that way, unless the request sets one direction for every piece (`azimuth_deg`).\n  - Every area left out is listed once, with a reason: outside the dataset; a shape that can't be filled, such as a hole outside its outline; too small, when no well runs through it; or over a limit, when its piece would pass the well limit or the fill's work limit, or its holes can't all be checked. A piece over a limit is skipped whole, and the pieces after it are still laid.\n- Limits: a request that reads an area file, or fills many areas at once, is at most 10 MB. A file may hold at most 5,000 areas, 200,000 vertices and 20,000 rings (outer rings and holes). A zipped shapefile holds at most 64 entries, and the files read from it are at most 32 MB each and 64 MB in all, unzipped. A file that needs more work than one request may take is refused as too complex, and the same file always gets the same answer. Reading pads takes the same file limits, and refuses a file whose pads would lay more wells than a plan takes, or need more fill work than one request may take. Filling many areas takes at most 5,000 areas and 200,000 vertices, and lays at most 10,000 wells, or the most wells a plan takes, when that is lower. Areas whose edges need more work to join than one request may take are refused as too complex."
                        },
                        {
                          "id": "economics",
                          "title": "Economics",
                          "markdown": "- Economics are simulated half-cycle economics: capex, IRR, payback and NPV from each well's forecast and EUR, priced on the server by POST /economics. Never compute them yourself.\n- Every result is priced with a named deck. The default is Illustrative Midland flat-price deck, id prototype-midland-flat: Illustrative: flat prices and costs for a Midland basin well, with Texas royalty and taxes; not a Novi price deck and not a forward curve. The decks are Illustrative Midland flat-price deck (id prototype-midland-flat) and Novi house deck, $70 oil and $3 gas (id house-70-3). On a model set whose basin is Haynesville, Illustrative Haynesville gas deck (id illustrative-haynesville-gas) comes first and is the default: Illustrative: drafted from public benchmarks, not a Novi default and not a forward curve. Flat prices, gas-weighted costs and Louisiana taxes, applied to East Texas wells too (for a Texas well, override severance_gas: 0.075); each value's note names its public source. GET /economics/decks lists a set's decks, its default first; GET /economics/deck lists each value with its unit and source.\n- NPV is discounted at the deck's discount_rate, which the answer echoes: NPV25 on the default deck.\n- Label every economics figure \"Simulated half-cycle economics, deck <name>\", and name the conventions used by their label (Yearly discounting or Monthly discounting), not their id:\n  - prototype: Yearly discounting, the default: NPV leaves year 1 (months 0 to 12) undiscounted and discounts each later year one more year at the annual rate; payback is in fractional months; IRR is the monthly rate annualized as (1+m)^12 − 1; capex is all at month 0.\n  - fe: Monthly discounting. Matches Novi's earlier Forecast Engine: the monthly rate m = (1+r)^(1/12) − 1, the cash flow of month n (0 is capex, 1 the first production month) discounted by (1+m)^n; payback in whole months from turn-on; IRR as under yearly discounting. Capex stays all at month 0, since a scenario has no spud or completion dates.\n- Every well needs a forecast and an EUR. A scenario without them comes back with a reason instead of numbers; report the reason."
                        },
                        {
                          "id": "provenance",
                          "title": "Provenance",
                          "markdown": "Every answer and chart made from this API carries one provenance line:\n- dataset: GET /dataset name;\n- as of: GET /dataset as_of, the date the data runs to;\n- model per stream: GET /dataset models, model_num for oil, gas and water;\n- request id: the X-Request-Id of the call the numbers came from (every response and error carries one);\n- API version: GET /health version, which GET /conventions repeats as api_version;\n- \"Sample data\" when GET /dataset sample_data is true.\n\nAs: `<dataset> · as of <as_of> · models oil <id>, gas <id>, water <id> · request <id> · API <version> · Sample data`."
                        },
                        {
                          "id": "payload",
                          "title": "Asking for data",
                          "markdown": "- Ask for the least data that answers the question, then more when asked.\n- Forecasts: summary: true and a few ip_days (as 180, 360 and 1080) before full curves. Ask for explanations only to answer why.\n- Wells: format=geojson with bbox, formation, q or operator, and a small limit; never the whole basin.\n- Plans: totals per design and GET /plans/{id}/stats before wells; then wells a page at a time with limit and cursor, sorted by a metric.\n- Lists page with limit and cursor: pass next_cursor back until it is null.\n- Full tables (monthly volumes, EUR per well, Arps parameters) come as export files from POST /exports, not in a reply."
                        },
                        {
                          "id": "sync",
                          "title": "Reading forecasts into another tool",
                          "markdown": "- A forecast curve is cumulative volume at each ip_day. It starts at 0 on day 0 and runs in a straight line from point to point.\n- The volume over any period is the cumulative at its end minus the cumulative at its start.\n- Past its last point, a curve with an EUR follows its decline extension to the EUR's day, then stays at the EUR. A curve without an EUR ends at its last point.\n- These rules hold on the full curve. Ask for every ip_day, with no ip_days filter, before you interpolate or extend it.\n- Novi's P10 is the low curve and P90 the high curve. See \"P10, P50 and P90\".\n- Once a plan made through POST /plans is done, its forecasts are stored and don't change. Only its name and whether it is saved can change. Curve points past model_months are built from its decline extension on each read, so a later release can move them.\n- A Legacy Forecast can't be changed or deleted through the API. Its numbers change when its run's results file is rewritten, or when a release changes how the server reads runs. The server then reads the run again.\n- With a state store, unsaved plans are deleted 90 days after they are made. Unsaving a plan starts a new 90 days from then. Saved plans stay until someone deletes them.\n- Without a state store, plans live only in memory. The server keeps its last few finished plans, and a restart loses them. Saving needs a state store.\n- A deleted plan leaves no record. It drops out of GET /plans, and reading it answers 404, as for a plan that never existed.\n- A well's key is unique within one plan only. A planned well's key is its place in the plan, as DRAWN-0, so the same key appears in every plan. A Legacy Forecast's wells keep their run's own key.\n- Key a well across plans by its well_uid from GET /plans/{id}/curves: 32 characters, the same on every read of the plan. A plan run again (from_plan) has a new id, so its wells get new well_uids.\n- To sync the forecasts that stay, saved plans and every Legacy Forecast, list `GET /plans?origin=all&kept=true&status=done&updated_from=<last sync start minus 15 minutes>&include=storage&limit=100&model_set=<id>` for each model set in GET /model-sets. Without model_set, it lists only the default set's v2 plans, beside every Legacy Forecast. The 15 minutes cover a change made just before your last sync started that the list didn't show yet.\n- Every set's list holds every Legacy Forecast, so send origin=v2 instead of origin=all for each set after the first.\n- With a state store, include=storage adds storage.updated_at to each v2 plan: its last stored change, which updated_from reads. A Legacy Forecast's storage is null.\n- Page by next_cursor until it is null, sending the same parameters each time.\n- A done v2 plan (origin.engine v2) keeps its stored forecasts. Take the v2 plan ids you haven't seen. A saved plan renamed since your last sync comes back with the same forecasts. To catch curve points a release moved, read a plan's curve pages again with each page's ETag as If-None-Match: 304 means nothing moved.\n- A Legacy Forecast (origin.engine fe) keeps its id when its numbers change. Read it again when its origin.indexed_at is newer than the copy you hold. That is when the server last read the run, as it does after its results file is rewritten or a release changes how runs are read. Its created_at moves only when the file is rewritten.\n- A Legacy Forecast the server hasn't read yet is counted in a fe_runs_pending warning, and a later sync lists it once it is read.\n- The lists never say that a plan was unsaved, deleted or expired. They leave it out. Now and then, send the same lists without updated_from and status, and drop the ids you hold that they don't list. Drop no Legacy Forecast when a page carried a fe_runs_pending or fe_runs_unavailable warning: that list may leave out one that is still there.\n- To read many wells' curves, use GET /plans/{id}/curves. It answers a page of wells at a time: 100 by default, up to 200 with limit. Pass next_cursor back as cursor until it is null.\n- Each curve there is the cumulative at day 30, 60, 90 and on to the EUR's day: cum[m-1] is the cumulative at day 30·m. These are the numbers the monthly export writes.\n- IP figures come from cum. The cumulative over a well's first n days, for n = 30·m, is cum[m-1]: IP30 is cum[0] and IP540 is cum[17]. The average daily rate over those days is that divided by n. The same holds for each P-level. Other values of n are not on the 30-day grid. When cum has no point there, or it is null, there is no figure for that n.\n- The first model_months points come from the model and the rest from the decline extension. A curve without an extension ends at model_months, and its note says why.\n- P10 and P90 come with p_levels=P50,P10,P90 on a plan made with bands. They reach the EUR only on a plan made with band_eur.\n- Read done plans only: a running or failed plan answers 409. Each page has an ETag. Send it back as If-None-Match to get 304 when nothing changed.\n- For calendar months, send start_date. til dates each well from its TIL date, else the plan's day (plan_day). A date as YYYY-MM-DD dates every well from that day. start_date_source says which.\n- Each curve then has calendar: its volume in each calendar month. C runs straight from 0 on the start date through each cum point, day 30·m after it, and stays at the last. A month's volume is C at the next month's first day minus C at its own, to 0.01.\n- The first month runs from the start date, so it is partial unless that date is a 1st. The last is the month that holds the last point, day 30·m of the last cum; when that day is a 1st, the month is there with volume 0. The volumes add up to the last cum within rounding."
                        }
                      ]
                    }
                  },
                  "decline_profiles": {
                    "summary": "include=decline_profiles",
                    "value": {
                      "api_version": "1.16.0",
                      "units": {
                        "oil": "bbl",
                        "gas": "mcf",
                        "water": "bbl",
                        "boe": "BOE",
                        "lateral_length": "ft",
                        "tvd": "ft",
                        "proppant": "lb/ft",
                        "fluid": "bbl/ft",
                        "money": "USD"
                      },
                      "boe": {
                        "gas_mcf_per_bbl": 6,
                        "label": "BOE (6:1)"
                      },
                      "p_levels": {
                        "low": "P10",
                        "high": "P90",
                        "convention": "P10 is the low curve and P90 the high one, as Novi labels them; SPE PRMS uses the reverse (P90 is its low, proved case)"
                      },
                      "sections": [
                        {
                          "id": "units",
                          "title": "Units",
                          "markdown": "- Oil and water are in bbl (barrels). Gas is in mcf (thousand cubic feet). Field names and descriptions carry the unit.\n- Volumes are cumulative at each ip_day, the days since first production. Rates are daily averages, in bbl/d and mcf/d.\n- Lengths and depths are in ft. Completions are fluid in bbl per lateral ft and proppant in lb per lateral ft.\n- Points are [lng, lat] in WGS 84 degrees.\n- To compare wells of different lengths, divide by the lateral length in ft and multiply by 1,000: \"per 1,000 ft\".\n- Keep the unit when you shorten a number: Mbbl is a thousand bbl, MMcf a thousand mcf."
                        },
                        {
                          "id": "boe",
                          "title": "BOE",
                          "markdown": "- BOE (barrels of oil equivalent) is oil plus gas at 6 mcf per bbl: BOE = oil bbl + gas mcf / 6.\n- Label it \"BOE (6:1)\" so the reader knows the ratio.\n- BOE needs both oil and gas when the forecast carries both: when either is missing, BOE is missing too. A forecast that carries only one of them, because its model set or source has no other, has BOE from that stream alone (oil bbl, or gas mcf / 6).\n- Water is not part of BOE."
                        },
                        {
                          "id": "p-levels",
                          "title": "P10, P50 and P90",
                          "markdown": "- P50 is the point forecast; label numbers from a forecast without bands \"P50\". Novi's P10 is the low curve and P90 the high curve.\n- That is the reverse of SPE PRMS. In the API's words: P10 is the low curve and P90 the high one, as Novi labels them; SPE PRMS uses the reverse (P90 is its low, proved case).\n- Whenever you show P10 or P90, say which convention it is, as \"Novi convention: P10 low, P90 high\".\n- P10 and P90 bound one well's forecast. The spread across a plan's wells is quantiles (q10, q50, q90), which are not P-levels; call them well quantiles."
                        },
                        {
                          "id": "eur",
                          "title": "EUR",
                          "markdown": "- EUR (estimated ultimate recovery) is the forecast extended by a decline-curve fit to the EUR day. It is not a model output.\n- EUR covers oil and gas; water has one only with eur_water: true, and BOE never reads it.\n- It is opt-in: eur: true on a forecast, a plan or a wells export.\n- Quote the settings from GET /dataset eur: defaults (eur_years, terminal_decline, b_min, b_max) and bounds. Do not state them from memory. Call the method a decline-curve fit to the EUR day rather than quoting eur.method.\n- A request's decline settings override the defaults and come back in its decline echo; quote those when a request set them, or each well's inputs.resolved.decline when the echo says per_well.\n- When GET /dataset eur.available is false, this server has no EUR. Say so instead of estimating one."
                        },
                        {
                          "id": "bands",
                          "title": "P10/P90 bands",
                          "markdown": "- Bands are a low (P10) and a high (P90) cumulative curve around each stream's forecast.\n- On the production models they are split conformal prediction bands, fit once per model and stored beside it, computed in the same model call as the forecast.\n- They are opt-in: bands: true on a forecast or plan. band_eur: true also fits each band's EUR.\n- GET /dataset bands says whether this server has them, for which streams, and the reason when not. On the production models, call them split conformal bands rather than quoting bands.method.\n- When bands are unavailable, or a stream has none, show P50 alone and say \"P50 only\". Never draw or estimate a band yourself.\n- Plan totals add the wells' P10 curves, and their P90 curves. A sum of P10s is not the plan's own P10."
                        },
                        {
                          "id": "input-checks",
                          "title": "Input checks",
                          "markdown": "- Every forecast design carries checks: the inputs the model rarely or never saw in training, checked on the oil model's rows against its training statistics.\n- out_of_range lists numeric inputs more than 5% of their training range (99th minus 1st percentile) below the 1st or above the 99th percentile of training, each with its value and that training range.\n- context lists neighbors' production outside the 1st to 99th percentile of training, each with its side: it describes the parent depletion near the well, which moves little with completions but does with where the lateral is drawn. above means more parent depletion nearby than nearly all training wells, below less: say so, not that an input is unusual. It does not set flagged. Tool rows give it as counts by side (context: {above, below}), and totals count the wells with any (context, or wells_context on plan totals), each only when there are any.\n- missing lists inputs left blank that are blank in under 5% of training rows. unknown_formation names a target formation the model has no training wells in.\n- When flagged is true, say how many inputs are outside the training data, name each with its value and range, and say the forecast is less certain.\n- Show the flag beside any number you quote from a well whose checks are flagged, and beside any plan total whose wells_flagged is above 0, saying how many wells it covers.\n- When checks.available is false, say the inputs were not checked, and why."
                        },
                        {
                          "id": "area-files",
                          "title": "Shapefiles and other area files",
                          "markdown": "- An area file is a zipped shapefile, GeoJSON, KML or KMZ. In a zip the .shp is enough: the .dbf adds the attributes and the .prj the coordinate system. Only polygons are read. A zip's first polygon layer is used, and a record of another shape is skipped.\n- The coordinate system is the one sent as `crs`, else the file's own: its .prj, the one a GeoJSON file names, or WGS 84 for KML and for GeoJSON in degrees that names none. Otherwise, or when the API does not read the file's system, it is detected: the first known system that places the coordinates on the dataset. The answer names the system and whether the request, the file or detection gave it. When detection gave it and other systems would also fit but place the areas elsewhere, the answer lists them with a warning. When detection finds none, coordinates in degrees are read as WGS 84 with a warning, and others are refused. Areas come back in WGS 84 longitude and latitude.\n- One record is one area, with its attributes: a shapefile record, a GeoJSON feature or a KML placemark. An area keeps the file's first 50 attributes, plus any that name it, each text value cut at 200 characters. A record is skipped when it has no area, is not a polygon, is damaged, has coordinates off the globe, or its .dbf row is marked deleted. The answer lists the first 100 skipped records with the reason and counts the rest. Shapefile records past the .dbf's last row are not read, with a warning.\n- A client may name the attribute field that names the areas (`name_field`), or several (`name_fields`, at most 5; send one or the other), whose values are joined in order by `name_separator`, one space by default, with blanks left out. With none named, the API picks a field with a usual name for names, such as a name or lease name field, that at least 90% of records fill, else the first text field whose filled values all differ. An area with no name value is \"Area N\", N being its record's number counting from one. Names need not differ, except in a file read as pads: there a pad with no name value is \"Pad N\", and a pad whose name repeats one kept before it is left out.\n- A hole is not part of its area. Acres leave it out, and wells laid on the area's whole shape stay out of it. A hole that lies wholly outside its outline is read as a part of its own, and one that crosses its outline or is as large is left out, each with a warning. Holes are checked in file order within a fixed amount of work per request. Past it, a plain read takes each later hole as the file gives it, with no warning; filling many areas and reading pads leave out an area whose holes can't all be checked. The single outline each area also carries, for clients that take one ring, is its largest part without its holes, simplified to at most 500 corners, and none when that ring can't be filled.\n- An area with several parts is one area, with one name and its parts' acres added. Wells laid on its whole shape fill every part.\n- An area whose bounding box misses the dataset's is still read, and marked as outside the dataset. Filling many areas skips it, and reading pads leaves it out.\n- Filling many areas at once:\n  - Areas, or parts of areas, that share an edge are laid as one piece of land: their edges run within 1 ft of each other along an unbroken 100 ft or more, or they overlap. A shared corner, or edges that touch only here and there, do not join them.\n  - A well may cross the line between joined areas. It never leaves the piece, and never runs through a hole that no other area covers. Land that two areas both cover is laid once.\n  - Setbacks (`setback_ft`, `setback_end_ft`) hold at the piece's outer edges and holes, not at the lines between its areas. Where two areas overlap, an edge that runs inside the other area still keeps its setbacks.\n  - Along each line, every unbroken stretch of land, less its setbacks, takes as many wells of the full `lateral_length_ft` as fit. When the land left over is at least `min_lateral_ft`, the stretch takes one more well, and all its wells are of equal length. Otherwise the full-length wells are centred on the stretch. A stretch shorter than the minimum takes no well.\n  - `lateral_length_ft` is required, from 1,000 to 30,000 ft. `min_lateral_ft` is 1,000 ft up to that length; left out, it is 85% of the length, at least 1,000 ft.\n  - Each piece's wells run along its largest part's longest edge, or square to that edge when the piece is longer that way, unless the request sets one direction for every piece (`azimuth_deg`).\n  - Every area left out is listed once, with a reason: outside the dataset; a shape that can't be filled, such as a hole outside its outline; too small, when no well runs through it; or over a limit, when its piece would pass the well limit or the fill's work limit, or its holes can't all be checked. A piece over a limit is skipped whole, and the pieces after it are still laid.\n- Limits: a request that reads an area file, or fills many areas at once, is at most 10 MB. A file may hold at most 5,000 areas, 200,000 vertices and 20,000 rings (outer rings and holes). A zipped shapefile holds at most 64 entries, and the files read from it are at most 32 MB each and 64 MB in all, unzipped. A file that needs more work than one request may take is refused as too complex, and the same file always gets the same answer. Reading pads takes the same file limits, and refuses a file whose pads would lay more wells than a plan takes, or need more fill work than one request may take. Filling many areas takes at most 5,000 areas and 200,000 vertices, and lays at most 10,000 wells, or the most wells a plan takes, when that is lower. Areas whose edges need more work to join than one request may take are refused as too complex."
                        },
                        {
                          "id": "economics",
                          "title": "Economics",
                          "markdown": "- Economics are simulated half-cycle economics: capex, IRR, payback and NPV from each well's forecast and EUR, priced on the server by POST /economics. Never compute them yourself.\n- Every result is priced with a named deck. The default is Illustrative Midland flat-price deck, id prototype-midland-flat: Illustrative: flat prices and costs for a Midland basin well, with Texas royalty and taxes; not a Novi price deck and not a forward curve. The decks are Illustrative Midland flat-price deck (id prototype-midland-flat) and Novi house deck, $70 oil and $3 gas (id house-70-3). On a model set whose basin is Haynesville, Illustrative Haynesville gas deck (id illustrative-haynesville-gas) comes first and is the default: Illustrative: drafted from public benchmarks, not a Novi default and not a forward curve. Flat prices, gas-weighted costs and Louisiana taxes, applied to East Texas wells too (for a Texas well, override severance_gas: 0.075); each value's note names its public source. GET /economics/decks lists a set's decks, its default first; GET /economics/deck lists each value with its unit and source.\n- NPV is discounted at the deck's discount_rate, which the answer echoes: NPV25 on the default deck.\n- Label every economics figure \"Simulated half-cycle economics, deck <name>\", and name the conventions used by their label (Yearly discounting or Monthly discounting), not their id:\n  - prototype: Yearly discounting, the default: NPV leaves year 1 (months 0 to 12) undiscounted and discounts each later year one more year at the annual rate; payback is in fractional months; IRR is the monthly rate annualized as (1+m)^12 − 1; capex is all at month 0.\n  - fe: Monthly discounting. Matches Novi's earlier Forecast Engine: the monthly rate m = (1+r)^(1/12) − 1, the cash flow of month n (0 is capex, 1 the first production month) discounted by (1+m)^n; payback in whole months from turn-on; IRR as under yearly discounting. Capex stays all at month 0, since a scenario has no spud or completion dates.\n- Every well needs a forecast and an EUR. A scenario without them comes back with a reason instead of numbers; report the reason."
                        },
                        {
                          "id": "provenance",
                          "title": "Provenance",
                          "markdown": "Every answer and chart made from this API carries one provenance line:\n- dataset: GET /dataset name;\n- as of: GET /dataset as_of, the date the data runs to;\n- model per stream: GET /dataset models, model_num for oil, gas and water;\n- request id: the X-Request-Id of the call the numbers came from (every response and error carries one);\n- API version: GET /health version, which GET /conventions repeats as api_version;\n- \"Sample data\" when GET /dataset sample_data is true.\n\nAs: `<dataset> · as of <as_of> · models oil <id>, gas <id>, water <id> · request <id> · API <version> · Sample data`."
                        },
                        {
                          "id": "payload",
                          "title": "Asking for data",
                          "markdown": "- Ask for the least data that answers the question, then more when asked.\n- Forecasts: summary: true and a few ip_days (as 180, 360 and 1080) before full curves. Ask for explanations only to answer why.\n- Wells: format=geojson with bbox, formation, q or operator, and a small limit; never the whole basin.\n- Plans: totals per design and GET /plans/{id}/stats before wells; then wells a page at a time with limit and cursor, sorted by a metric.\n- Lists page with limit and cursor: pass next_cursor back until it is null.\n- Full tables (monthly volumes, EUR per well, Arps parameters) come as export files from POST /exports, not in a reply."
                        },
                        {
                          "id": "sync",
                          "title": "Reading forecasts into another tool",
                          "markdown": "- A forecast curve is cumulative volume at each ip_day. It starts at 0 on day 0 and runs in a straight line from point to point.\n- The volume over any period is the cumulative at its end minus the cumulative at its start.\n- Past its last point, a curve with an EUR follows its decline extension to the EUR's day, then stays at the EUR. A curve without an EUR ends at its last point.\n- These rules hold on the full curve. Ask for every ip_day, with no ip_days filter, before you interpolate or extend it.\n- Novi's P10 is the low curve and P90 the high curve. See \"P10, P50 and P90\".\n- Once a plan made through POST /plans is done, its forecasts are stored and don't change. Only its name and whether it is saved can change. Curve points past model_months are built from its decline extension on each read, so a later release can move them.\n- A Legacy Forecast can't be changed or deleted through the API. Its numbers change when its run's results file is rewritten, or when a release changes how the server reads runs. The server then reads the run again.\n- With a state store, unsaved plans are deleted 90 days after they are made. Unsaving a plan starts a new 90 days from then. Saved plans stay until someone deletes them.\n- Without a state store, plans live only in memory. The server keeps its last few finished plans, and a restart loses them. Saving needs a state store.\n- A deleted plan leaves no record. It drops out of GET /plans, and reading it answers 404, as for a plan that never existed.\n- A well's key is unique within one plan only. A planned well's key is its place in the plan, as DRAWN-0, so the same key appears in every plan. A Legacy Forecast's wells keep their run's own key.\n- Key a well across plans by its well_uid from GET /plans/{id}/curves: 32 characters, the same on every read of the plan. A plan run again (from_plan) has a new id, so its wells get new well_uids.\n- To sync the forecasts that stay, saved plans and every Legacy Forecast, list `GET /plans?origin=all&kept=true&status=done&updated_from=<last sync start minus 15 minutes>&include=storage&limit=100&model_set=<id>` for each model set in GET /model-sets. Without model_set, it lists only the default set's v2 plans, beside every Legacy Forecast. The 15 minutes cover a change made just before your last sync started that the list didn't show yet.\n- Every set's list holds every Legacy Forecast, so send origin=v2 instead of origin=all for each set after the first.\n- With a state store, include=storage adds storage.updated_at to each v2 plan: its last stored change, which updated_from reads. A Legacy Forecast's storage is null.\n- Page by next_cursor until it is null, sending the same parameters each time.\n- A done v2 plan (origin.engine v2) keeps its stored forecasts. Take the v2 plan ids you haven't seen. A saved plan renamed since your last sync comes back with the same forecasts. To catch curve points a release moved, read a plan's curve pages again with each page's ETag as If-None-Match: 304 means nothing moved.\n- A Legacy Forecast (origin.engine fe) keeps its id when its numbers change. Read it again when its origin.indexed_at is newer than the copy you hold. That is when the server last read the run, as it does after its results file is rewritten or a release changes how runs are read. Its created_at moves only when the file is rewritten.\n- A Legacy Forecast the server hasn't read yet is counted in a fe_runs_pending warning, and a later sync lists it once it is read.\n- The lists never say that a plan was unsaved, deleted or expired. They leave it out. Now and then, send the same lists without updated_from and status, and drop the ids you hold that they don't list. Drop no Legacy Forecast when a page carried a fe_runs_pending or fe_runs_unavailable warning: that list may leave out one that is still there.\n- To read many wells' curves, use GET /plans/{id}/curves. It answers a page of wells at a time: 100 by default, up to 200 with limit. Pass next_cursor back as cursor until it is null.\n- Each curve there is the cumulative at day 30, 60, 90 and on to the EUR's day: cum[m-1] is the cumulative at day 30·m. These are the numbers the monthly export writes.\n- IP figures come from cum. The cumulative over a well's first n days, for n = 30·m, is cum[m-1]: IP30 is cum[0] and IP540 is cum[17]. The average daily rate over those days is that divided by n. The same holds for each P-level. Other values of n are not on the 30-day grid. When cum has no point there, or it is null, there is no figure for that n.\n- The first model_months points come from the model and the rest from the decline extension. A curve without an extension ends at model_months, and its note says why.\n- P10 and P90 come with p_levels=P50,P10,P90 on a plan made with bands. They reach the EUR only on a plan made with band_eur.\n- Read done plans only: a running or failed plan answers 409. Each page has an ETag. Send it back as If-None-Match to get 304 when nothing changed.\n- For calendar months, send start_date. til dates each well from its TIL date, else the plan's day (plan_day). A date as YYYY-MM-DD dates every well from that day. start_date_source says which.\n- Each curve then has calendar: its volume in each calendar month. C runs straight from 0 on the start date through each cum point, day 30·m after it, and stays at the last. A month's volume is C at the next month's first day minus C at its own, to 0.01.\n- The first month runs from the start date, so it is partial unless that date is a 1st. The last is the month that holds the last point, day 30·m of the last cum; when that day is a 1st, the month is there with volume 0. The volumes add up to the last cum within rounding."
                        }
                      ],
                      "decline_profiles": [
                        {
                          "id": "valnav",
                          "title": "Val Nav",
                          "declines": [
                            "nominal"
                          ],
                          "year_days": 365.2425,
                          "months": "calendar",
                          "volumes": "integral",
                          "ratio_slope": "time",
                          "verified": true,
                          "verified_against": "Val Nav's own results in 12 cases, at the tolerances those cases set, but for two of their values, which came from another implementation, not Val Nav; every ratio case declines on volume, none on time",
                          "markdown": "- Declines are nominal, as fractions per year of 365.2425 days: that year reproduces the type-well segment volumes Val Nav exported.\n- Monthly volumes are calendar months: for oil, gas, water and condensate segments each month is the exact integral of the rate over its days; a stream made from a ratio follows the ratio segments line below. A qf of 0 runs a segment to its end date.\n- A segment of oil, gas, water or condensate stops 100 years after it starts, even when its end date, qf or df is later.\n- Ratio segments (GOR in scf/bbl, OGR, CGR and WGR in bbl/MMcf, WOR in bbl/bbl) decline with time unless a segment says volume, and a ratio's last segment runs to its parent stream's end. On a time slope a ratio's day is its parent's volume that day times the ratio's average over the day; on a volume slope it is the exact integral over the parent's volume.\n- Matches Val Nav's own results in 12 cases, at the tolerances those cases set, but for two of their values, which came from another implementation, not Val Nav; every ratio case declines on volume, none on time.\n- Those two values: an OGR case's December, checked instead against Val Nav's December for the same gas in a CGR case; and the month a GOR reaches its cap, which that implementation holds at the cap all month and this profile caps from the day the GOR reaches it."
                        },
                        {
                          "id": "mosaic",
                          "title": "Mosaic",
                          "declines": [
                            "nominal",
                            "tangent",
                            "secant"
                          ],
                          "year_days": 365.24,
                          "months": "calendar",
                          "volumes": "integral",
                          "ratio_slope": "volume",
                          "verified": false,
                          "verified_against": null,
                          "markdown": "- Declines are nominal (Di), tangent effective (Dei) or secant effective (Desi), as fractions per year of 365.24 days.\n- Monthly volumes are calendar months: for oil, gas, water and condensate segments each month is the exact integral of the rate over its days; a stream made from a ratio follows the ratio segments line below.\n- A segment of oil, gas, water or condensate stops 100 years after it starts, even when its end date, qf or df is later.\n- Ratio segments (GOR in scf/bbl, OGR, CGR and WGR in bbl/MMcf, WOR in bbl/bbl) decline with the parent stream's cumulative volume unless a segment says time, and a ratio's last segment runs to its parent stream's end. On a time slope a ratio's day is its parent's volume that day times the ratio's average over the day; on a volume slope it is the exact integral over the parent's volume."
                        },
                        {
                          "id": "combocurve",
                          "title": "ComboCurve",
                          "declines": [
                            "secant"
                          ],
                          "year_days": 365.25,
                          "months": "calendar",
                          "volumes": "start_of_day",
                          "ratio_slope": "time",
                          "verified": true,
                          "verified_against": "ComboCurve's published totals in five public forecast-comparison cases (flat, linear, exponential, harmonic, hyperbolic), each within 0.001%; those cases publish totals only, not each month's volume; none has a ratio segment",
                          "markdown": "- Declines are secant effective, as fractions per year of 365.25 days; an exponential segment's secant and tangent declines are the same.\n- A day's volume is the rate at the start of the day held for the whole day, so a decline reads slightly above the exact integral.\n- Monthly volumes are calendar months from midnight UTC, and days start at start_date's time of day. With a date, or a date-time at midnight UTC, each month holds whole days. With a date-time at any other time, a month boundary splits a day, and each month takes that day's volume in proportion to its hours.\n- A segment of oil, gas, water or condensate stops 100 years after it starts, even when its end date, qf or df is later.\n- Ratio segments (GOR in scf/bbl, OGR, CGR and WGR in bbl/MMcf, WOR in bbl/bbl) decline with time unless a segment says volume, and a ratio's last segment runs to its parent stream's end. On either slope a ratio's day is its parent's volume that day times the ratio at the start of the day.\n- Matches ComboCurve's published totals in five public forecast-comparison cases (flat, linear, exponential, harmonic, hyperbolic), each within 0.001%; those cases publish totals only, not each month's volume; none has a ratio segment."
                        },
                        {
                          "id": "novi",
                          "title": "Novi",
                          "declines": [
                            "nominal"
                          ],
                          "year_days": 365,
                          "months": "30-day",
                          "volumes": "integral",
                          "ratio_slope": "time",
                          "verified": true,
                          "verified_against": "Novi's own arps.csv rows: each q_stop from q_start, b and d_nominal",
                          "markdown": "- Declines are nominal, as fractions per year of 365 days, as arps.csv's d_nominal; an exponential row's d_i is per day, and its q_stop is the rate on its last day, day_stop - 1.\n- Months are 30-day months from ip day 0: for oil, gas, water and condensate segments each month is the exact integral of the rate over its days; a stream made from a ratio follows the ratio segments line below.\n- A segment of oil, gas, water or condensate stops 100 years after it starts, even when its end date, qf or df is later.\n- Ratio segments (GOR in scf/bbl, OGR, CGR and WGR in bbl/MMcf, WOR in bbl/bbl) decline with time unless a segment says volume, and a ratio's last segment runs to its parent stream's end. On a time slope a ratio's day is its parent's volume that day times the ratio's average over the day; on a volume slope it is the exact integral over the parent's volume.\n- Matches Novi's own arps.csv rows: each q_stop from q_start, b and d_nominal."
                        },
                        {
                          "id": "aries",
                          "title": "ARIES",
                          "declines": [
                            "secant"
                          ],
                          "year_days": 360,
                          "months": "30-day",
                          "volumes": "integral",
                          "ratio_slope": "time",
                          "verified": false,
                          "verified_against": "read back only against Novi's own ARIES export; no result ARIES computed",
                          "markdown": "- Declines are secant effective, as fractions per year of 360 days, twelve 30-day months, as Novi's ARIES export writes them; an exponential segment's secant and tangent declines are the same.\n- B/M and M/M rates are per 30-day month, B/D and M/D per day. MOS and YRS count from START, IMOS and IYRS from the segment's start, and a life of x EXP runs until the decline reaches x%.\n- A segment of oil, gas, water or condensate stops 100 years after it starts, even when its end date, qf or df is later.\n- ARIES ratio segments aren't read: each is a row issue."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/me": {
      "get": {
        "operationId": "getMe",
        "tags": [
          "Service"
        ],
        "summary": "Get who this request is",
        "description": "The request's tenant, user and role, as the server reads them. A user Novi's sign-in edge signed in has their customer as tenant, and role `staff` for customer `novi`, else `customer`; the server's configured user has its default tenant and role `staff`.",
        "responses": {
          "200": {
            "description": "Who this request is.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                },
                "example": {
                  "tenant": "example",
                  "user": {
                    "id": "7",
                    "email": "user@example.com"
                  },
                  "role": "customer"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        },
        "parameters": []
      }
    },
    "/field-dictionary": {
      "get": {
        "operationId": "getFieldDictionary",
        "tags": [
          "Service"
        ],
        "summary": "Get what fields and Legacy Forecasts names mean",
        "description": "Names in one read: fields, export columns, model tables and Legacy Forecasts names. None is an alias: the API accepts none of them. It changes only with a deploy, so it carries an ETag.\n\n**Fields.** `fields`: the properties of WellInput, Design, PlanWellSummary, ForecastWell, ResolvedInputs, ShapRow, ContributingWell, SpacingNeighbor, less those they ignore, each with its type, the unit its name carries and its description. GET /openapi.json has the other schemas'.\n\n**Export columns.** `export_columns`: every export table's columns as GET /export-formats lists them with eur and eur_water (`well` with a plan's description); `added_by_plan` marks those only some plans add to wells. `model_tables` names the tables that write a plan's own columns.\n\n**Legacy Forecasts names.** `fe_names`: the output names of Novi's earlier Forecast Engine, each with the field or export column that carries it, or \"none\". Its note says which names it leaves out.",
        "responses": {
          "200": {
            "description": "The field dictionary.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FieldDictionary"
                },
                "example": {
                  "api_version": "1.63.0",
                  "fields": [
                    {
                      "name": "tvd_ft",
                      "schema": "WellInput",
                      "type": "number",
                      "unit": "ft",
                      "description": "True vertical depth in ft. Blank estimates it from the structure grid and nearby wells."
                    }
                  ],
                  "export_columns": [
                    {
                      "table": "monthly",
                      "file": "monthly.csv",
                      "name": "oil_bbl",
                      "unit": "bbl",
                      "description": "Oil produced in the month; past the forecast, from the EUR's extension",
                      "default": true,
                      "stream": "oil",
                      "added_by_plan": false
                    }
                  ],
                  "model_tables": [
                    {
                      "table": "calc_features",
                      "file": "calc_features.csv",
                      "description": "Each well's calculated model features"
                    }
                  ],
                  "fe_names": {
                    "note": "Each row gives the name and the field or export column that carries it, or \"none\".",
                    "not_mapped": [
                      "user_name"
                    ],
                    "groups": [
                      {
                        "title": "Wells and designs",
                        "note": null,
                        "rows": [
                          {
                            "name": "completion_name",
                            "fe_tables": [
                              "forecasts",
                              "inputs",
                              "shap",
                              "date_aligned_forecasts"
                            ],
                            "v2": "`designs[].name`, and `design` in export tables",
                            "none": false,
                            "columns": [
                              {
                                "table": "designs",
                                "name": "design"
                              }
                            ]
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        },
        "parameters": []
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApi",
        "tags": [
          "Service"
        ],
        "summary": "Get this document",
        "description": "The OpenAPI 3.1 description of this API: every operation with its parameters, request and response schemas and examples. Import it into a client generator or an API tool.",
        "responses": {
          "200": {
            "description": "This document.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "An OpenAPI 3.1 document.",
                  "required": [
                    "openapi",
                    "info",
                    "paths"
                  ],
                  "properties": {
                    "openapi": {
                      "type": "string",
                      "description": "OpenAPI version."
                    },
                    "info": {
                      "type": "object"
                    },
                    "paths": {
                      "type": "object"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "parameters": []
      }
    },
    "/wells/search": {
      "post": {
        "operationId": "searchWells",
        "tags": [
          "Wells"
        ],
        "summary": "List the wells in a unit",
        "description": "Lists the existing wells in a unit, taking GET /wells' filters in a JSON body and answering with its response schemas, so a client that reads GET /wells reads this. Each well gains `area_distance_ft`, and wells come inside first, then nearest.\n\n**Scope.** Send `area` or `polygon`, not both. A well is in the unit when its lateral midpoint (the point GET /wells' `bbox` filters on) is inside the area, on its edge or within `buffer_ft` of it. With `match: lateral`, any part of its lateral counts, which picks up wells that cross the unit's edge.\n\n- Holes are left out and a MultiPolygon's parts count together. `buffer_ft` is measured to the nearest edge, a hole's included, on a flat earth about the well.\n- Rings need at least 3 corners and some area, and at most 200,000 vertices in all, as many as POST /areas reads (400 with `details.max` and `details.count`). `area` and `polygon` say which other rings are a 400.\n- A scope that needs more work than one request may take (about a second) is a 400 \"too complex\" with `details.max_work`, and the same scope always fares the same: simplify the outline, split it or send a smaller `buffer_ft`.\n- Errors are 400 with `details.field`.\n\n**Filters.** GET /wells' query parameters work as they do there, sent as body fields, but for `bbox`, `near` and `radius_mi`: the scope replaces them. `operators` and `keys` are arrays, not comma lists, and an empty `keys` is a 400.\n\n**The answer.** `area_distance_ft` is 0 inside the area or on its edge, else feet from it, rounded and at least 1, from the lateral midpoint (with `match: lateral`, the nearer of it and the lateral). Wells come inside first, then nearest, then by wellbore key; `sort` replaces that order. To page either `format`, send the same body again with `cursor` set to `next_cursor`. POST /units/summary sums up the same scope by formation and operator, with the grids.\n\n**Outlines.** `outlines` takes 1 to 10 scopes in place of `area`, `polygon`, `buffer_ft` and `match`; errors name `outlines[i].area`, `outlines[i].buffer_ft` and so on. A well is kept when it is in every outline without `exclude` and in none with `exclude: true`, so an excluded outline's `buffer_ft` widens what it leaves out.\n\n- `area_distance_ft` is the largest of the well's distances to the outlines without `exclude`, and wells come in that order, then by wellbore key. One outline answers as the same scope sent alone.\n- `count`, the page totals and `cursor` cover the kept wells.\n- A 400 names `outlines` for none or more than 10, only excluded ones, more than 200,000 vertices over all of them (`details.max` and `details.count`), or too much work together (\"too complex\", `details.max_work`).\n- `outlines` with `area`, `polygon`, `buffer_ft` or `match` is a 400 naming that field.",
        "requestBody": {
          "required": true,
          "description": "The scope, and GET /wells' filters and paging.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WellsSearchRequest"
              },
              "examples": {
                "geojson": {
                  "summary": "A page of an area's wells, 660 ft buffer",
                  "value": {
                    "area": {
                      "type": "Polygon",
                      "coordinates": [
                        [
                          [
                            -101.95,
                            31.93
                          ],
                          [
                            -101.93,
                            31.93
                          ],
                          [
                            -101.93,
                            31.96
                          ],
                          [
                            -101.95,
                            31.96
                          ],
                          [
                            -101.95,
                            31.93
                          ]
                        ],
                        [
                          [
                            -101.945,
                            31.945
                          ],
                          [
                            -101.94,
                            31.945
                          ],
                          [
                            -101.94,
                            31.94
                          ],
                          [
                            -101.945,
                            31.94
                          ],
                          [
                            -101.945,
                            31.945
                          ]
                        ]
                      ]
                    },
                    "buffer_ft": 660,
                    "format": "geojson",
                    "limit": 2
                  }
                },
                "columns": {
                  "summary": "Laterals crossing a ring, a few columns",
                  "value": {
                    "polygon": [
                      [
                        -101.945,
                        31.94
                      ],
                      [
                        -101.94,
                        31.94
                      ],
                      [
                        -101.94,
                        31.945
                      ],
                      [
                        -101.945,
                        31.945
                      ]
                    ],
                    "buffer_ft": 330,
                    "fields": [
                      "well_name",
                      "formation",
                      "area_distance_ft"
                    ]
                  }
                },
                "outlines": {
                  "summary": "An area's wells, less those a lasso touches",
                  "value": {
                    "outlines": [
                      {
                        "area": {
                          "type": "Polygon",
                          "coordinates": [
                            [
                              [
                                -101.95,
                                31.93
                              ],
                              [
                                -101.93,
                                31.93
                              ],
                              [
                                -101.93,
                                31.96
                              ],
                              [
                                -101.95,
                                31.96
                              ],
                              [
                                -101.95,
                                31.93
                              ]
                            ],
                            [
                              [
                                -101.945,
                                31.945
                              ],
                              [
                                -101.94,
                                31.945
                              ],
                              [
                                -101.94,
                                31.94
                              ],
                              [
                                -101.945,
                                31.94
                              ],
                              [
                                -101.945,
                                31.945
                              ]
                            ]
                          ]
                        },
                        "buffer_ft": 660
                      },
                      {
                        "area": {
                          "type": "Polygon",
                          "coordinates": [
                            [
                              [
                                -101.948,
                                31.951
                              ],
                              [
                                -101.938,
                                31.949
                              ],
                              [
                                -101.933,
                                31.955
                              ],
                              [
                                -101.94,
                                31.959
                              ],
                              [
                                -101.947,
                                31.957
                              ],
                              [
                                -101.948,
                                31.951
                              ]
                            ]
                          ]
                        },
                        "match": "lateral",
                        "exclude": true
                      }
                    ],
                    "format": "geojson",
                    "limit": 2,
                    "fields": [
                      "well_name",
                      "area_distance_ft"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The wells in scope, inside first.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WellColumns"
                },
                "example": {
                  "format": "columns",
                  "count": 6,
                  "columns": {
                    "wellbore_key": [
                      "SB329-04866",
                      "SB329-05341",
                      "SB329-05415",
                      "SB329-05344",
                      "SB329-05443",
                      "SB329-04803"
                    ],
                    "well_name": [
                      "REDDING TRUST 11-23 5WB",
                      "REDDING TRUST 11-23 3LS",
                      "REDDING TRUST 11-23 6WB",
                      "REDDING TRUST 11-23 4LS",
                      "REDDING TRUST 11-23 7WB",
                      "REDDING TRUST 11-23 4WB"
                    ],
                    "formation": [
                      "WOLFCAMP B",
                      "LOWER SPRABERRY SHALE",
                      "WOLFCAMP B",
                      "LOWER SPRABERRY SHALE",
                      "WOLFCAMP B",
                      "WOLFCAMP B"
                    ],
                    "area_distance_ft": [
                      0,
                      0,
                      0,
                      211,
                      217,
                      220
                    ]
                  }
                }
              },
              "application/geo+json": {
                "schema": {
                  "$ref": "#/components/schemas/WellFeatureCollection"
                },
                "examples": {
                  "page": {
                    "summary": "A page of an area's wells, 660 ft buffer",
                    "value": {
                      "type": "FeatureCollection",
                      "count": 45,
                      "next_cursor": "bzoy",
                      "features": [
                        {
                          "type": "Feature",
                          "id": "SB329-01199",
                          "geometry": {
                            "type": "Point",
                            "coordinates": [
                              -101.94591,
                              31.93111
                            ]
                          },
                          "properties": {
                            "wellbore_key": "SB329-01199",
                            "well_name": "PRENTICE 39-40 3WB",
                            "operator": "Sample Operator A",
                            "formation": "WOLFCAMP B",
                            "first_prod": "2014-08-03",
                            "lateral_length": 4790,
                            "tvd_td": 9704,
                            "cum_boe_12": 76077,
                            "shl_lon": -101.95555,
                            "shl_lat": 31.9322,
                            "heel_lon": -101.95367,
                            "heel_lat": 31.931,
                            "bhl_lon": -101.93815,
                            "bhl_lat": 31.93122,
                            "area_distance_ft": 0
                          }
                        },
                        {
                          "type": "Feature",
                          "id": "SB329-01245",
                          "geometry": {
                            "type": "Point",
                            "coordinates": [
                              -101.94581,
                              31.93253
                            ]
                          },
                          "properties": {
                            "wellbore_key": "SB329-01245",
                            "well_name": "PRENTICE 39-40 3JM",
                            "operator": "Sample Operator A",
                            "formation": "JO MILL",
                            "first_prod": "2014-08-04",
                            "lateral_length": 4790,
                            "tvd_td": 7931,
                            "cum_boe_12": 85548,
                            "shl_lon": -101.95556,
                            "shl_lat": 31.93228,
                            "heel_lon": -101.95357,
                            "heel_lat": 31.93243,
                            "bhl_lon": -101.93805,
                            "bhl_lat": 31.93264,
                            "area_distance_ft": 0
                          }
                        }
                      ]
                    }
                  },
                  "outlines": {
                    "summary": "A page of an area's wells, less those a lasso touches",
                    "value": {
                      "type": "FeatureCollection",
                      "count": 28,
                      "next_cursor": "bzoy",
                      "features": [
                        {
                          "type": "Feature",
                          "id": "SB329-01199",
                          "geometry": {
                            "type": "Point",
                            "coordinates": [
                              -101.94591,
                              31.93111
                            ]
                          },
                          "properties": {
                            "wellbore_key": "SB329-01199",
                            "well_name": "PRENTICE 39-40 3WB",
                            "area_distance_ft": 0
                          }
                        },
                        {
                          "type": "Feature",
                          "id": "SB329-01245",
                          "geometry": {
                            "type": "Point",
                            "coordinates": [
                              -101.94581,
                              31.93253
                            ]
                          },
                          "properties": {
                            "wellbore_key": "SB329-01245",
                            "well_name": "PRENTICE 39-40 3JM",
                            "area_distance_ft": 0
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/units/summary": {
      "post": {
        "operationId": "summarizeUnit",
        "tags": [
          "Wells"
        ],
        "summary": "Summarize a unit's wells, grids and completions",
        "description": "What a unit holds, in one request: its area, the existing wells inside and around it by formation, operator and year, each formation's grid ranges, and completion medians. Use it before filling a unit.\n\n**Scope.** Send `area` or `polygon`, not both. A well is in the unit when its lateral midpoint (the point GET /wells' `bbox` filters on) is inside the area, on its edge or within `buffer_ft` of it. With `match: lateral`, any part of its lateral counts, which picks up wells that cross the unit's edge.\n\n- Holes are left out and a MultiPolygon's parts count together. `buffer_ft` is measured to the nearest edge, a hole's included, on a flat earth about the well.\n- Rings need at least 3 corners and some area, and at most 200,000 vertices in all, as many as POST /areas reads (400 with `details.max` and `details.count`). `area` and `polygon` say which other rings are a 400.\n- A scope that needs more work than one request may take (about a second) is a 400 \"too complex\" with `details.max_work`, and the same scope always fares the same: simplify the outline, split it or send a smaller `buffer_ft`.\n- Errors are 400 with `details.field`.\n\n**The answer.** A median leaves out wells without that value, and is null when none has it.\n\n- `area`: measured as POST /areas measures it, so the two agree.\n- `wells`: those in scope, `inside` the area and in the `buffer`, by formation, by operator (the top 10 by wells, then an Other row) and by first-production year.\n- `formations`: every formation, top to bottom, with its wells in scope and each subsurface grid's min, median and max over the cells (GET /subsurface/grids/{feature_name}'s lattice points) whose centres fall inside the area, not the buffer.\n  - Over 2,500 cells in the area's bbox, the first inside each square of a 50 × 50 lattice over the bbox is used, and `sampled` is true.\n  - `grids` is null for a formation without grids or with no cell inside. For an area smaller than a cell, sample a well path with GET /subsurface/sample.\n- `completions`: by formation, the median fluid (bbl/ft, to 0.1) and proppant (lb/ft, to 1) of the in-scope wells with both, or empty. The per-well values are those GET /completions/defaults takes medians of, without its 180-day online window, so these cover the unit's wells of every vintage.\n\n**Only some formations.** `formation` (a name, names separated by commas, or an array) keeps only those formations' wells, formations and completions.\n\n**Before you fill it.** The wells inside are the unit's existing wells, but forecasts and plans space each new well against every existing well within the spacing radius (GET /dataset `spacing.search_radius_ft`), inside the unit or not: send `buffer_ft` to see those around it. List the wells with POST /wells/search (same scope). Fill the unit with POST /layouts/fill (the same `area`, every part filled and holes left out, or an area's `fill.polygon`; and `long_axis_azimuth_deg`), or as a `layout` in POST /plans.",
        "requestBody": {
          "required": true,
          "description": "The scope, and optionally formations.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UnitSummaryRequest"
              },
              "example": {
                "area": {
                  "type": "Polygon",
                  "coordinates": [
                    [
                      [
                        -101.95,
                        31.93
                      ],
                      [
                        -101.93,
                        31.93
                      ],
                      [
                        -101.93,
                        31.96
                      ],
                      [
                        -101.95,
                        31.96
                      ],
                      [
                        -101.95,
                        31.93
                      ]
                    ],
                    [
                      [
                        -101.945,
                        31.945
                      ],
                      [
                        -101.94,
                        31.945
                      ],
                      [
                        -101.94,
                        31.94
                      ],
                      [
                        -101.945,
                        31.94
                      ],
                      [
                        -101.945,
                        31.945
                      ]
                    ]
                  ]
                },
                "buffer_ft": 660,
                "formation": [
                  "WOLFCAMP A",
                  "WOLFCAMP B"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The unit.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnitSummary"
                },
                "example": {
                  "area": {
                    "acres": 1490.74,
                    "long_axis_azimuth_deg": 0,
                    "bbox": [
                      -101.95,
                      31.93,
                      -101.93,
                      31.96
                    ],
                    "in_dataset": true
                  },
                  "wells": {
                    "inside": 7,
                    "buffer": 12,
                    "by_formation": [
                      {
                        "formation": "WOLFCAMP A",
                        "wells": 6,
                        "inside": 0,
                        "median_lateral_ft": 7505,
                        "median_tvd_ft": 9125,
                        "median_cum_boe_12": 246804,
                        "total_cum_boe_12": 1443390,
                        "median_cum_boe_12_per_1000_ft": 32910,
                        "first_prod_earliest": "2019-04-12",
                        "first_prod_latest": "2019-07-08"
                      },
                      {
                        "formation": "WOLFCAMP B",
                        "wells": 13,
                        "inside": 7,
                        "median_lateral_ft": 4820,
                        "median_tvd_ft": 9677,
                        "median_cum_boe_12": 168089,
                        "total_cum_boe_12": 2262044,
                        "median_cum_boe_12_per_1000_ft": 32412,
                        "first_prod_earliest": "2014-06-17",
                        "first_prod_latest": "2025-09-10"
                      }
                    ],
                    "by_operator": [
                      {
                        "operator": "Sample Operator A",
                        "wells": 19
                      }
                    ],
                    "by_first_year": [
                      {
                        "year": 2014,
                        "wells": 3
                      },
                      {
                        "year": 2019,
                        "wells": 6
                      },
                      {
                        "year": 2020,
                        "wells": 6
                      },
                      {
                        "year": 2025,
                        "wells": 4
                      }
                    ]
                  },
                  "formations": [
                    {
                      "formation": "WOLFCAMP A",
                      "label": "Wolfcamp A",
                      "wells": 6,
                      "inside": 0,
                      "has_grids": true,
                      "grids": {
                        "novi_structuraldepth": {
                          "feature_name": "novi_structuraldepth_wolfcamp_a",
                          "unit": "ft",
                          "cells": 7,
                          "sampled": false,
                          "min": -8923.6,
                          "median": -8916,
                          "max": -8910.1
                        },
                        "novi_thickness_avg": {
                          "feature_name": "novi_thickness_avg_wolfcamp_a",
                          "unit": "ft",
                          "cells": 7,
                          "sampled": false,
                          "min": 427.74,
                          "median": 430.6,
                          "max": 435.5
                        },
                        "novi_thickness_ofnet": {
                          "feature_name": "novi_thickness_ofnet_wolfcamp_a",
                          "unit": "ft",
                          "cells": 7,
                          "sampled": false,
                          "min": 303.02,
                          "median": 308.7,
                          "max": 318.72
                        },
                        "novi_bvi_avg": {
                          "feature_name": "novi_bvi_avg_wolfcamp_a",
                          "unit": "fraction",
                          "cells": 7,
                          "sampled": false,
                          "min": 0.051431,
                          "median": 0.052133,
                          "max": 0.052704
                        },
                        "novi_bvi_ofnet": {
                          "feature_name": "novi_bvi_ofnet_wolfcamp_a",
                          "unit": "fraction",
                          "cells": 7,
                          "sampled": false,
                          "min": 0.059287,
                          "median": 0.059784,
                          "max": 0.060259
                        }
                      }
                    },
                    {
                      "formation": "WOLFCAMP B",
                      "label": "Wolfcamp B",
                      "wells": 13,
                      "inside": 7,
                      "has_grids": true,
                      "grids": {
                        "novi_structuraldepth": {
                          "feature_name": "novi_structuraldepth_wolfcamp_b",
                          "unit": "ft",
                          "cells": 12,
                          "sampled": false,
                          "min": -9355.5,
                          "median": -9349.2,
                          "max": -9342.7
                        },
                        "novi_thickness_avg": {
                          "feature_name": "novi_thickness_avg_wolfcamp_b",
                          "unit": "ft",
                          "cells": 12,
                          "sampled": false,
                          "min": 654.48,
                          "median": 665.59,
                          "max": 674.64
                        },
                        "novi_thickness_ofnet": {
                          "feature_name": "novi_thickness_ofnet_wolfcamp_b",
                          "unit": "ft",
                          "cells": 12,
                          "sampled": false,
                          "min": 412.8,
                          "median": 424.2,
                          "max": 434.75
                        },
                        "novi_bvi_avg": {
                          "feature_name": "novi_bvi_avg_wolfcamp_b",
                          "unit": "fraction",
                          "cells": 12,
                          "sampled": false,
                          "min": 0.052199,
                          "median": 0.0528,
                          "max": 0.053316
                        },
                        "novi_bvi_ofnet": {
                          "feature_name": "novi_bvi_ofnet_wolfcamp_b",
                          "unit": "fraction",
                          "cells": 12,
                          "sampled": false,
                          "min": 0.058091,
                          "median": 0.058865,
                          "max": 0.059587
                        }
                      }
                    }
                  ],
                  "completions": [
                    {
                      "formation": "WOLFCAMP A",
                      "fluid_bbl_per_ft": 53.2,
                      "proppant_lb_per_ft": 2140,
                      "wells": 6
                    },
                    {
                      "formation": "WOLFCAMP B",
                      "fluid_bbl_per_ft": 48.3,
                      "proppant_lb_per_ft": 2258,
                      "wells": 13
                    }
                  ],
                  "warnings": []
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/wells/facets": {
      "get": {
        "operationId": "listWellFacets",
        "tags": [
          "Wells"
        ],
        "summary": "Count wells by value",
        "description": "Counts of wells by value, for pickers and range sliders, without downloading wells. Name up to 6 fields in `facets`, which lists the text and numeric ones.\n\n**Text fields.** Values with well counts, most wells first; `limit` caps them and `others` sums the rest. `contains` keeps the values containing some text, word starts first: type-ahead for operators.\n\n**Numeric fields.** Unit, min, max, and q10, q50 and q90 (type 7, to 0.1: quantiles of wells, not P-level bands), with a histogram of `bins` equal-width bars. Edges are rounded as shown, covering min and max; a bar counts the wells within its shown edges, the last closed. On the whole-number fields (`first_year`, `stage_count`) a bar is a whole number of values wide: with span = max − min + 1 values, each is ceil(span / `bins`) wide, at most `bins` bars, one per value when the range fits, with edges halfway between values (2018.5), so a `_min` and `_max` from any two edges select exactly those bars. A non-finite value counts as missing.\n\n**Filters.** Every GET /wells filter narrows the count; the top-level `wells` is the count with all of them. A facet ignores its own exact filter (`operators`, `formation`, `county`, or its `_min` and `_max`), so a picker keeps showing the values it could add.\n\n**Errors.** 400 with `details.field`: no `facets`, an unknown one (with `details.allowed`), more than 6, `contains` without a text facet, `bins` without a numeric one, or a GET /wells filter error.\n\n**Caching.** Dataset-derived: cached, with an `ETag`.",
        "parameters": [
          {
            "name": "facets",
            "in": "query",
            "required": true,
            "description": "The fields to count, comma-separated, each once, at most 6: text `operator`, `formation`, `county`, `subbasin`, `state`, `basin`; numeric `first_year`, `lateral_length`, `tvd_td`, `cum_boe_12`, `cum_oil_12`, `cum_gas_12`, `cum_boe_life`, `stage_count`, `fluid_bbl_per_ft`, `proppant_lb_per_ft`, `cum_boe_12_per_1000_ft`, `cum_oil_12_per_1000_ft`, `cum_gas_12_per_1000_ft`.",
            "schema": {
              "type": "string"
            },
            "example": "operator,lateral_length"
          },
          {
            "name": "contains",
            "in": "query",
            "description": "With a text facet (400 without one): keep the values containing this text, ignoring case, those with a word starting with it first, then the rest, each most wells first, then by name; at most 100 characters.",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Values per text facet; `others` sums the rest.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            }
          },
          {
            "name": "bins",
            "in": "query",
            "description": "With a numeric facet (400 without one): histogram bins; for a whole-number field (`first_year`, `stage_count`) the most bars, since each is a whole number of values wide.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "formation",
            "in": "query",
            "description": "Only these formations: one name or a comma-separated list, case-insensitive, as `WOLFCAMP A,WOLFCAMP B`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bbox",
            "in": "query",
            "description": "Only wells whose lateral midpoint is inside `west,south,east,north` (degrees), as `-102.05,31.9,-101.85,32.05`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Only wells whose name or wellbore key contains this text, ignoring case: `woodard trust` matches WOODARD TRUST 32-44 2WB. Leading and trailing spaces are ignored; up to 100 characters (400 past it).",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "operator",
            "in": "query",
            "description": "Only wells whose operator contains this text, ignoring case; up to 100 characters (400 past it).",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "operators",
            "in": "query",
            "style": "form",
            "explode": true,
            "description": "Only wells of these operators: exact names, case-insensitive. Repeat the parameter for each name (`operators=A&operators=B`), since operator names can contain commas; at most 50, each at most 100 characters (400 past either, with `details.max` and `details.count`). `operator` stays a substring match. GET /wells/facets lists the names.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 100
              },
              "maxItems": 50
            }
          },
          {
            "name": "county",
            "in": "query",
            "description": "Only wells in these counties: exact names, case-insensitive, comma-separated, at most 50.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "near",
            "in": "query",
            "description": "Only wells within `radius_mi` of this point: `lng,lat` in WGS 84 degrees, longitude first as in `bbox`, measured in great-circle miles to each lateral's midpoint. Combines with every other filter; 400 when it isn't two numbers within -180 to 180 and -90 to 90. Facets count the wells it keeps; no well comes back.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "radius_mi",
            "in": "query",
            "description": "With `near` (400 without it): how far from it to look, in miles, a decimal greater than 0 and at most 100 written as digits (2 or 2.5); default 5.",
            "schema": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 100,
              "default": 5
            }
          },
          {
            "name": "lateral_length_min",
            "in": "query",
            "description": "Only wells whose `lateral_length` is at least this, in ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lateral_length_max",
            "in": "query",
            "description": "Only wells whose `lateral_length` is at most this, in ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "tvd_td_min",
            "in": "query",
            "description": "Only wells whose `tvd_td` is at least this, in ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "tvd_td_max",
            "in": "query",
            "description": "Only wells whose `tvd_td` is at most this, in ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_oil_12_min",
            "in": "query",
            "description": "Only wells whose `cum_oil_12` is at least this, in bbl.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_oil_12_max",
            "in": "query",
            "description": "Only wells whose `cum_oil_12` is at most this, in bbl.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_gas_12_min",
            "in": "query",
            "description": "Only wells whose `cum_gas_12` is at least this, in mcf.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_gas_12_max",
            "in": "query",
            "description": "Only wells whose `cum_gas_12` is at most this, in mcf.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_boe_12_min",
            "in": "query",
            "description": "Only wells whose `cum_boe_12` is at least this, in BOE.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_boe_12_max",
            "in": "query",
            "description": "Only wells whose `cum_boe_12` is at most this, in BOE.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_oil_life_min",
            "in": "query",
            "description": "Only wells whose `cum_oil_life` is at least this, in bbl.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_oil_life_max",
            "in": "query",
            "description": "Only wells whose `cum_oil_life` is at most this, in bbl.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_gas_life_min",
            "in": "query",
            "description": "Only wells whose `cum_gas_life` is at least this, in mcf.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_gas_life_max",
            "in": "query",
            "description": "Only wells whose `cum_gas_life` is at most this, in mcf.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_boe_life_min",
            "in": "query",
            "description": "Only wells whose `cum_boe_life` is at least this, in BOE.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_boe_life_max",
            "in": "query",
            "description": "Only wells whose `cum_boe_life` is at most this, in BOE.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "total_proppant_min",
            "in": "query",
            "description": "Only wells whose `total_proppant` is at least this, in lb.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "total_proppant_max",
            "in": "query",
            "description": "Only wells whose `total_proppant` is at most this, in lb.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "total_fluid_min",
            "in": "query",
            "description": "Only wells whose `total_fluid` is at least this, in bbl.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "total_fluid_max",
            "in": "query",
            "description": "Only wells whose `total_fluid` is at most this, in bbl.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "stage_count_min",
            "in": "query",
            "description": "Only wells whose `stage_count` is at least this, in stages.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "stage_count_max",
            "in": "query",
            "description": "Only wells whose `stage_count` is at most this, in stages.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "first_year_min",
            "in": "query",
            "description": "Only wells whose `first_year` is at least this, in years.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "first_year_max",
            "in": "query",
            "description": "Only wells whose `first_year` is at most this, in years.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "fluid_bbl_per_ft_min",
            "in": "query",
            "description": "Only wells whose `fluid_bbl_per_ft` is at least this, in bbl/ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "fluid_bbl_per_ft_max",
            "in": "query",
            "description": "Only wells whose `fluid_bbl_per_ft` is at most this, in bbl/ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "proppant_lb_per_ft_min",
            "in": "query",
            "description": "Only wells whose `proppant_lb_per_ft` is at least this, in lb/ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "proppant_lb_per_ft_max",
            "in": "query",
            "description": "Only wells whose `proppant_lb_per_ft` is at most this, in lb/ft.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_boe_12_per_1000_ft_min",
            "in": "query",
            "description": "Only wells whose `cum_boe_12_per_1000_ft` is at least this, in BOE per 1,000 ft of lateral.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_boe_12_per_1000_ft_max",
            "in": "query",
            "description": "Only wells whose `cum_boe_12_per_1000_ft` is at most this, in BOE per 1,000 ft of lateral.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_oil_12_per_1000_ft_min",
            "in": "query",
            "description": "Only wells whose `cum_oil_12_per_1000_ft` is at least this, in bbl per 1,000 ft of lateral.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_oil_12_per_1000_ft_max",
            "in": "query",
            "description": "Only wells whose `cum_oil_12_per_1000_ft` is at most this, in bbl per 1,000 ft of lateral.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_gas_12_per_1000_ft_min",
            "in": "query",
            "description": "Only wells whose `cum_gas_12_per_1000_ft` is at least this, in mcf per 1,000 ft of lateral.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "cum_gas_12_per_1000_ft_max",
            "in": "query",
            "description": "Only wells whose `cum_gas_12_per_1000_ft` is at most this, in mcf per 1,000 ft of lateral.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "first_prod_min",
            "in": "query",
            "description": "Only wells whose `first_prod` is on or after this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "first_prod_max",
            "in": "query",
            "description": "Only wells whose `first_prod` is on or before this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "last_prod_min",
            "in": "query",
            "description": "Only wells whose `last_prod` is on or after this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "last_prod_max",
            "in": "query",
            "description": "Only wells whose `last_prod` is on or before this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "frac_date_min",
            "in": "query",
            "description": "Only wells whose `frac_date` is on or after this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "frac_date_max",
            "in": "query",
            "description": "Only wells whose `frac_date` is on or before this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "til_date_min",
            "in": "query",
            "description": "Only wells whose `til_date` is on or after this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "til_date_max",
            "in": "query",
            "description": "Only wells whose `til_date` is on or before this day, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "keys",
            "in": "query",
            "description": "Only these wells: wellbore keys, exact, comma-separated, such as `SB329-01414,SB329-01415`.\n\nA repeated `keys` adds its list, and a repeat counts once. At most 50 keys (400 naming `keys` past it, with `details.max` and `details.count`). An empty `keys=` means every well; a value with no key, such as `,`, is a 400. A key the dataset lacks matches nothing. Facets count the wells that match, not which keys did.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "Counts by facet, in the order asked.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WellFacets"
                },
                "example": {
                  "wells": 4294,
                  "facets": {
                    "operator": {
                      "type": "text",
                      "distinct": 11,
                      "missing": 0,
                      "values": [
                        {
                          "value": "Sample Operator A",
                          "wells": 703
                        },
                        {
                          "value": "BRINDLEWOOD RESOURCES INC",
                          "wells": 679
                        }
                      ],
                      "others": {
                        "values": 9,
                        "wells": 2912
                      }
                    },
                    "lateral_length": {
                      "type": "number",
                      "unit": "ft",
                      "wells": 4294,
                      "missing": 0,
                      "min": 4540,
                      "max": 15000,
                      "quantiles": {
                        "q10": 4720,
                        "q50": 9960,
                        "q90": 12750
                      },
                      "histogram": {
                        "edges": [
                          4540,
                          6632,
                          8724,
                          10816,
                          12908,
                          15000
                        ],
                        "counts": [
                          1212,
                          572,
                          1726,
                          467,
                          317
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/wells/typecurve": {
      "post": {
        "operationId": "buildTypeCurve",
        "tags": [
          "Wells"
        ],
        "summary": "Build type curves from existing wells",
        "description": "Production type curves of existing wells: the spread of their actual cumulative volumes and daily rates at each ip_day (days since first production). Use it for an analog type curve: a formation's recent wells, a unit's wells, or a forecast's contributing wells.\n\n**Wells.** By key (`wells`), GET /wells' filters and ranges, a unit (`area` or `polygon` with `buffer_ft` and `match`, as POST /wells/search), `bbox` or `near`, all combined, except a unit with `bbox` or `near`. Without one of those three, wells without a location count too; with one, a keyed well without a location is counted in `excluded.no_location`.\n\n**What comes back.** Per ip_day: how many wells reach it, their plain mean and the `quantiles` asked (q10, q50 and q90 by default). These are quantiles of wells: `q10` is the 10th-percentile well, not Novi's per-well P10. Under `min_wells` wells, both are null. Wells align on ip_day, not peak, and count while their history reaches it, so the tail is fewer, older wells. A rate is the average daily rate over the step ending at the ip_day. BOE is oil + gas / 6, for wells with both; on a set serving only one of oil and gas, BOE is that one alone (gas / 6).\n\n**Normalizing.** `normalize_lateral_ft` scales each well linearly to that lateral (`1000`: per 1,000 ft), leaving out and counting wells without one. `min_lateral_ft` leaves out shorter laterals, whose scaled volumes swell (`excluded.short_lateral`). `pooled: true` adds `pooled`: the wells' summed values over their summed laterals × `normalize_lateral_ft`, so a long lateral weighs more than in `mean`; null where `mean` is.\n\n**A fixed cohort.** `cohort_ip_day` keeps only wells with every asked stream and measure at every 30-day ip_day up to it (BOE needs oil and gas), so a cumulative line can't fall as wells drop out. `ip_days` then defaults to every 30 days up to it (none when fewer than `min_wells` are left), and any sent must be multiples of 30 up to it (else a 400). Left-out wells are counted in `excluded.short_history`; groups are cut from the cohort.\n\n**First month.** A well first producing in the dataset's first production month (GET /dataset `first_production`) may have produced earlier. `exclude_floor: true` leaves those wells out (`excluded.floor`) unless their `til_date` is in that month; GET /wells/{key}?include=floors marks them.\n\n**Exclusions.** Floor, short lateral and short history apply after the other reasons, in that order; a well counts under the first, and each `excluded` key is present only when its option is sent.\n\n**More.** `group_by` gives one curve per formation, operator or first-production year (the 12 largest). `include: [\"wells\"]` adds each well's series, up to 100 wells.\n\n**Limits.** 1,000 keys, 240 ip_days (1 or multiples of 30, up to 7,200), and a scope of 25,000 wells (400 with `details.max` and `details.count`: narrow it). On a set serving fewer than three streams, `streams` defaults to its own and BOE, and naming another is a 400.\n\n**Errors.** 400 with `details.field`. No match is a 200 with `used: 0` and one empty curve, or no curves with `group_by`.",
        "requestBody": {
          "required": true,
          "description": "Which wells, and what to compute; every key is optional.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TypeCurveRequest"
              },
              "example": {
                "formation": "WOLFCAMP A",
                "first_prod_min": "2021-01-01",
                "streams": [
                  "oil"
                ],
                "measures": [
                  "cum"
                ],
                "normalize_lateral_ft": 1000,
                "ip_days": [
                  30,
                  360,
                  1080
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The type curves.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TypeCurveResponse"
                },
                "example": {
                  "wells": 2424,
                  "used": 2424,
                  "excluded": {
                    "no_production": 0,
                    "no_lateral": 0,
                    "no_location": 0
                  },
                  "normalize_lateral_ft": 1000,
                  "min_wells": 5,
                  "units": {
                    "oil": "bbl",
                    "gas": "mcf",
                    "water": "bbl",
                    "boe": "BOE",
                    "rate": "per day"
                  },
                  "ip_days": [
                    30,
                    360,
                    1080
                  ],
                  "curves": [
                    {
                      "group": null,
                      "wells": 2424,
                      "streams": {
                        "oil": {
                          "cum": {
                            "wells": [
                              2372,
                              1936,
                              1141
                            ],
                            "mean": [
                              2370.2,
                              21694.4,
                              40144.4
                            ],
                            "q10": [
                              1635.9,
                              14929.4,
                              27298.8
                            ],
                            "q50": [
                              2286.2,
                              20960.1,
                              38807.4
                            ],
                            "q90": [
                              3241.1,
                              29601.1,
                              54599.6
                            ]
                          }
                        }
                      }
                    }
                  ],
                  "groups_left_out": 0
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/wells/production": {
      "post": {
        "operationId": "getWellsProduction",
        "tags": [
          "Wells"
        ],
        "summary": "Get several wells' production",
        "description": "Several existing wells' production in one request, each as GET /wells/{key}/production answers it, to overlay a forecast's contributing wells (their spread: POST /wells/typecurve).\n\n**Limits.** Up to 50 keys, in request order, a repeated key once. `ip_days` keeps only those rows (1, then multiples of 30), each well's stopping where its history does. A key the dataset lacks is a 400 naming it (`details.key`).",
        "requestBody": {
          "required": true,
          "description": "Wellbore keys, and optionally ip_days.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WellsProductionRequest"
              },
              "example": {
                "keys": [
                  "SB329-01414",
                  "SB329-01450"
                ],
                "ip_days": [
                  30,
                  360
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Each well's production, in request order.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WellsProduction"
                },
                "example": {
                  "count": 2,
                  "wells": [
                    {
                      "wellbore_key": "SB329-01414",
                      "count": 2,
                      "units": {
                        "oil": "bbl/d",
                        "gas": "mcf/d",
                        "water": "bbl/d",
                        "cum_oil": "bbl",
                        "cum_gas": "mcf",
                        "cum_water": "bbl"
                      },
                      "rows": [
                        {
                          "date": "2015-07-25",
                          "ip_day": 30,
                          "oil": 489.48,
                          "gas": 631.76,
                          "water": 1423.34,
                          "cum_oil": 14244,
                          "cum_gas": 18383,
                          "cum_water": 42243
                        },
                        {
                          "date": "2016-06-19",
                          "ip_day": 360,
                          "oil": 281.07,
                          "gas": 531.47,
                          "water": 467.57,
                          "cum_oil": 146740,
                          "cum_gas": 229870,
                          "cum_water": 279564
                        }
                      ]
                    },
                    {
                      "wellbore_key": "SB329-01450",
                      "count": 2,
                      "units": {
                        "oil": "bbl/d",
                        "gas": "mcf/d",
                        "water": "bbl/d",
                        "cum_oil": "bbl",
                        "cum_gas": "mcf",
                        "cum_water": "bbl"
                      },
                      "rows": [
                        {
                          "date": "2015-07-27",
                          "ip_day": 30,
                          "oil": 1027.83,
                          "gas": 1823.24,
                          "water": 1866.72,
                          "cum_oil": 29912,
                          "cum_gas": 53054,
                          "cum_water": 54993
                        },
                        {
                          "date": "2016-06-21",
                          "ip_day": 360,
                          "oil": 469.67,
                          "gas": 1220.73,
                          "water": 642.3,
                          "cum_oil": 268963,
                          "cum_gas": 573520,
                          "cum_water": 391601
                        }
                      ]
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/wells/{key}/predictions": {
      "parameters": [
        {
          "$ref": "#/components/parameters/WellKey"
        }
      ],
      "get": {
        "operationId": "getWellPredictions",
        "tags": [
          "Wells"
        ],
        "summary": "Get a well's stored predictions beside its actuals",
        "description": "The build's stored prediction for an existing well beside its actuals, per stream: `predicted` (the pre-refit `train` fit's cumulative at each ip_day), `actual` and `ape`, |predicted − actual| / actual (null without an actual above 0).\n\n**Split.** `holdout`: the train fit never saw the well. `train`: in-sample (`in_sample: true`), so its error reads about twice as good; hide these by default. A stream without a stored prediction has `split: null` and a `reason` saying whether the build stored none for it or the dataset lacks that split's predictions.\n\n**Caching.** Dataset-derived: cached, with an `ETag`.",
        "responses": {
          "200": {
            "description": "The well's predictions per stream.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WellPredictions"
                },
                "example": {
                  "wellbore_key": "SB003-02244",
                  "sample_data": true,
                  "streams": {
                    "oil": {
                      "model_num": "M20260930-sample-O-d1",
                      "fit": "train",
                      "split": "holdout",
                      "in_sample": false,
                      "unit": "bbl",
                      "ip_days": [
                        360,
                        720,
                        1080
                      ],
                      "predicted": [
                        183214,
                        277495,
                        342019
                      ],
                      "actual": [
                        180778,
                        273993,
                        null
                      ],
                      "ape": [
                        0.0135,
                        0.0128,
                        null
                      ]
                    },
                    "gas": {
                      "model_num": "M20260930-sample-G-d1",
                      "fit": "train",
                      "split": "holdout",
                      "in_sample": false,
                      "unit": "mcf",
                      "ip_days": [
                        360,
                        720,
                        1080
                      ],
                      "predicted": [
                        417764,
                        711845,
                        948465
                      ],
                      "actual": [
                        416928,
                        708693,
                        null
                      ],
                      "ape": [
                        0.002,
                        0.0044,
                        null
                      ]
                    },
                    "water": {
                      "model_num": "M20260930-sample-W-d1",
                      "fit": "train",
                      "split": "holdout",
                      "in_sample": false,
                      "unit": "bbl",
                      "ip_days": [
                        360,
                        720,
                        1080
                      ],
                      "predicted": [
                        399515,
                        583755,
                        714304
                      ],
                      "actual": [
                        409922,
                        606532,
                        null
                      ],
                      "ape": [
                        0.0254,
                        0.0376,
                        null
                      ]
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ]
      }
    },
    "/model-sets": {
      "get": {
        "operationId": "listModelSets",
        "tags": [
          "Service"
        ],
        "summary": "List the model sets",
        "description": "The model sets this server can serve, with each one's status: the set answering without `model_set` first, then `default` (unless retired), then the release file's sets in order. It never loads a set. Send a set's `id` as `model_set` on any dataset-scoped operation.\n\n**Includes.** `include` adds more about each set (see the parameter). Staff send include=pins for what each set is served from: the release, this environment's fork of it, or its own set.\n\n**What a set is.** A dataset (wells, production, subsurface grids, spacing) with oil, gas and water models, or some of them. `default` is the base dataset; the others are published sets the release file pins, loaded on first use (`status` `idle`, then `loading`) and checked against their manifest. A set that failed to load is `unavailable` with an `error`, and is tried again a minute later.\n\n**Streams.** A set's forecasts, plans, explanations, bands, EUR, type curves and exports carry only its `streams`; BOE counts an unserved oil or gas as 0. Naming another stream (in `decline`, `eur_water`, an export's streams or columns, a type curve, drivers, stats, a wells `sort` or a comparison `metric`) is a 400 `invalid_argument` listing the served ones in `details.allowed`. Economics prices only served streams (condensate in the oil slot at the oil price and differential); on a set serving neither oil nor gas, economics, drivers and ARIES are 400s.\n\n**The default set.** A server may answer requests without `model_set` from a published set (GET /model-sets `default` names it); `model_set=default` still reaches the base dataset. A server may also retire `default`: then it isn't listed, GET /model-sets/default is a 404 and `model_set=default` is a 400 naming the set answering instead.\n\n**Tenant sets.** An environment's own set may be scoped to tenants: staff and those tenants' users see it, and to anyone else it is an unknown id.",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "description": "Any of these, comma-separated or repeated, each once; any other value is a 400 with details.field include.\n\n- `model_type`: how each set's models were built: causal, standard or null.\n- `facts`: figures about each set's data and models.\n- `catalog`: each set's curated catalog entry, or null.\n- `frame`: the units each set's own data and models are in.\n- `vintage`: the month of each set's build, YYYY-MM, or null.\n- `subsurface_sampling`: where each set's grids are read at a well.\n- `formation_labels`: `grid` when each set's formations come from its own structure grids.\n- `pins` (staff only, else a 403): what each set's entry is served from.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The model sets.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelSetList"
                },
                "examples": {
                  "all": {
                    "summary": "Model sets",
                    "value": {
                      "default": "default",
                      "model_sets": [
                        {
                          "id": "default",
                          "label": "SAMPLE_Midland_Sep2026",
                          "basin": "Midland",
                          "publisher": null,
                          "default": true,
                          "status": "ready",
                          "error": null,
                          "models": {
                            "oil": "M20260930-sample-O-d1",
                            "gas": "M20260930-sample-G-d1",
                            "water": "M20260930-sample-W-d1"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "dataset": "SAMPLE_Midland_Sep2026",
                            "dataset_id": 9001,
                            "build_num": "S20260930"
                          }
                        },
                        {
                          "id": "novicast-midland-2610",
                          "label": "Midland 2610",
                          "basin": "Midland",
                          "publisher": "NoviCast",
                          "default": false,
                          "status": "idle",
                          "error": null,
                          "models": {
                            "oil": "M20261014-novicast-O-d1-prod",
                            "gas": "M20261014-novicast-G-d1-prod",
                            "water": "M20261014-novicast-W-d1-prod"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "customer": "novicast",
                            "dataset_id": 6171,
                            "dataset": "Midland Inventory Update 2610",
                            "build_num": "B20261013-230336"
                          }
                        }
                      ]
                    }
                  },
                  "model_type": {
                    "summary": "include=model_type",
                    "value": {
                      "default": "default",
                      "model_sets": [
                        {
                          "id": "default",
                          "label": "SAMPLE_Midland_Sep2026",
                          "basin": "Midland",
                          "publisher": null,
                          "default": true,
                          "status": "ready",
                          "error": null,
                          "models": {
                            "oil": "M20260930-sample-O-d1",
                            "gas": "M20260930-sample-G-d1",
                            "water": "M20260930-sample-W-d1"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "dataset": "SAMPLE_Midland_Sep2026",
                            "dataset_id": 9001,
                            "build_num": "S20260930"
                          },
                          "model_type": "standard"
                        },
                        {
                          "id": "novicast-midland-2610",
                          "label": "Midland 2610",
                          "basin": "Midland",
                          "publisher": "NoviCast",
                          "default": false,
                          "status": "idle",
                          "error": null,
                          "models": {
                            "oil": "M20261014-novicast-O-d1-prod",
                            "gas": "M20261014-novicast-G-d1-prod",
                            "water": "M20261014-novicast-W-d1-prod"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "customer": "novicast",
                            "dataset_id": 6171,
                            "dataset": "Midland Inventory Update 2610",
                            "build_num": "B20261013-230336"
                          },
                          "model_type": "causal"
                        }
                      ]
                    }
                  },
                  "facts": {
                    "summary": "include=model_type,facts",
                    "value": {
                      "default": "default",
                      "model_sets": [
                        {
                          "id": "default",
                          "label": "SAMPLE_Midland_Sep2026",
                          "basin": "Midland",
                          "publisher": null,
                          "default": true,
                          "status": "ready",
                          "error": null,
                          "models": {
                            "oil": "M20260930-sample-O-d1",
                            "gas": "M20260930-sample-G-d1",
                            "water": "M20260930-sample-W-d1"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "dataset": "SAMPLE_Midland_Sep2026",
                            "dataset_id": 9001,
                            "build_num": "S20260930"
                          },
                          "model_type": "standard",
                          "facts": {
                            "well_count": 18000,
                            "training_wells": 11321,
                            "holdout_wells": 6233,
                            "formation_count": 8,
                            "target_zone_count": 8,
                            "as_of": "2026-09-30",
                            "forecast_days": 1080,
                            "feature_count": 13
                          }
                        },
                        {
                          "id": "novicast-midland-2610",
                          "label": "Midland 2610",
                          "basin": "Midland",
                          "publisher": "NoviCast",
                          "default": false,
                          "status": "idle",
                          "error": null,
                          "models": {
                            "oil": "M20261014-novicast-O-d1-prod",
                            "gas": "M20261014-novicast-G-d1-prod",
                            "water": "M20261014-novicast-W-d1-prod"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "customer": "novicast",
                            "dataset_id": 6171,
                            "dataset": "Midland Inventory Update 2610",
                            "build_num": "B20261013-230336"
                          },
                          "model_type": "causal",
                          "facts": null
                        }
                      ]
                    }
                  },
                  "catalog": {
                    "summary": "include=catalog (illustrative values)",
                    "value": {
                      "default": "default",
                      "model_sets": [
                        {
                          "id": "default",
                          "label": "SAMPLE_Midland_Sep2026",
                          "basin": "Midland",
                          "publisher": null,
                          "default": true,
                          "status": "ready",
                          "error": null,
                          "models": {
                            "oil": "M20260930-sample-O-d1",
                            "gas": "M20260930-sample-G-d1",
                            "water": "M20260930-sample-W-d1"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "dataset": "SAMPLE_Midland_Sep2026",
                            "dataset_id": 9001,
                            "build_num": "S20260930"
                          },
                          "catalog": null
                        },
                        {
                          "id": "example-basin-2609",
                          "label": "Example Basin 2609",
                          "basin": "Midland",
                          "publisher": "NoviCast",
                          "default": false,
                          "status": "idle",
                          "error": null,
                          "models": {
                            "oil": "M20261014-novicast-O-d1-prod",
                            "gas": "M20261014-novicast-G-d1-prod",
                            "water": "M20261014-novicast-W-d1-prod"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "customer": "novicast",
                            "dataset_id": 6171,
                            "dataset": "Midland Inventory Update 2610",
                            "build_num": "B20261013-230336"
                          },
                          "catalog": {
                            "source": "Novi Intel Product Basin Report Models",
                            "report": "Example Basin Report",
                            "published": "2026-09-30",
                            "vintage": "2026-09",
                            "status": "published",
                            "dataset": "Example Basin Inventory 2609",
                            "accuracy": {
                              "oil": {
                                "mape_ip90": 0.172,
                                "mape_ip1080": 0.214,
                                "ape_ip90": 0.151,
                                "ape_ip1080": -0.019
                              },
                              "gas": {
                                "mape_ip90": 0.188,
                                "mape_ip1080": 0.231,
                                "ape_ip90": null,
                                "ape_ip1080": null
                              }
                            },
                            "notes": null
                          }
                        }
                      ]
                    }
                  },
                  "frame": {
                    "summary": "include=frame (illustrative metric set)",
                    "value": {
                      "default": "default",
                      "model_sets": [
                        {
                          "id": "default",
                          "label": "SAMPLE_Midland_Sep2026",
                          "basin": "Midland",
                          "publisher": null,
                          "default": true,
                          "status": "ready",
                          "error": null,
                          "models": {
                            "oil": "M20260930-sample-O-d1",
                            "gas": "M20260930-sample-G-d1",
                            "water": "M20260930-sample-W-d1"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "dataset": "SAMPLE_Midland_Sep2026",
                            "dataset_id": 9001,
                            "build_num": "S20260930"
                          },
                          "frame": {
                            "length": "ft",
                            "fluid_per_length": "bbl/ft",
                            "proppant_per_length": "lb/ft",
                            "production": {
                              "oil": "bbl",
                              "gas": "mcf",
                              "water": "bbl"
                            },
                            "grid_length": "ft"
                          }
                        },
                        {
                          "id": "example-metric-2610",
                          "label": "Example Metric 2610",
                          "basin": "Montney",
                          "publisher": "Novi",
                          "default": false,
                          "status": "idle",
                          "error": null,
                          "models": {
                            "oil": "M20261009-example-O-d1",
                            "gas": "M20261009-example-G-d1",
                            "water": "M20261009-example-W-d1"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "dataset": "Example Metric Inventory 2610"
                          },
                          "frame": {
                            "length": "m",
                            "fluid_per_length": "m3/m",
                            "proppant_per_length": "t/m",
                            "production": {
                              "oil": "bbl",
                              "gas": "mcf",
                              "water": "bbl"
                            },
                            "grid_length": "m"
                          }
                        }
                      ]
                    }
                  },
                  "subsurface_sampling": {
                    "summary": "include=subsurface_sampling",
                    "value": {
                      "default": "default",
                      "model_sets": [
                        {
                          "id": "default",
                          "label": "SAMPLE_Midland_Sep2026",
                          "basin": "Midland",
                          "publisher": null,
                          "default": true,
                          "status": "ready",
                          "error": null,
                          "models": {
                            "oil": "M20260930-sample-O-d1",
                            "gas": "M20260930-sample-G-d1",
                            "water": "M20260930-sample-W-d1"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "dataset": "SAMPLE_Midland_Sep2026",
                            "dataset_id": 9001,
                            "build_num": "S20260930"
                          },
                          "subsurface_sampling": "MIDPOINT"
                        },
                        {
                          "id": "novicast-midland-2610",
                          "label": "Midland 2610",
                          "basin": "Midland",
                          "publisher": "NoviCast",
                          "default": false,
                          "status": "ready",
                          "error": null,
                          "models": {
                            "oil": "M20261014-novicast-O-d1-prod",
                            "gas": "M20261014-novicast-G-d1-prod",
                            "water": "M20261014-novicast-W-d1-prod"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "customer": "novicast",
                            "dataset_id": 6171,
                            "dataset": "Midland Inventory Update 2610",
                            "build_num": "B20261013-230336"
                          },
                          "subsurface_sampling": "BOTTOM_HOLE"
                        }
                      ]
                    }
                  },
                  "formation_labels": {
                    "summary": "include=formation_labels (illustrative set)",
                    "value": {
                      "default": "default",
                      "model_sets": [
                        {
                          "id": "default",
                          "label": "SAMPLE_Midland_Sep2026",
                          "basin": "Midland",
                          "publisher": null,
                          "default": true,
                          "status": "ready",
                          "error": null,
                          "models": {
                            "oil": "M20260930-sample-O-d1",
                            "gas": "M20260930-sample-G-d1",
                            "water": "M20260930-sample-W-d1"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "dataset": "SAMPLE_Midland_Sep2026",
                            "dataset_id": 9001,
                            "build_num": "S20260930"
                          }
                        },
                        {
                          "id": "example-basin-2609",
                          "label": "Example Basin 2609",
                          "basin": "Midland",
                          "publisher": "NoviCast",
                          "default": false,
                          "status": "idle",
                          "error": null,
                          "models": {
                            "oil": "M20261014-novicast-O-d1-prod",
                            "gas": "M20261014-novicast-G-d1-prod",
                            "water": "M20261014-novicast-W-d1-prod"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "customer": "novicast",
                            "dataset_id": 6171,
                            "dataset": "Midland Inventory Update 2610",
                            "build_num": "B20261013-230336"
                          },
                          "formation_labels": "grid"
                        }
                      ]
                    }
                  },
                  "pins": {
                    "summary": "include=pins (staff only, illustrative fork)",
                    "value": {
                      "default": "default",
                      "model_sets": [
                        {
                          "id": "default",
                          "label": "SAMPLE_Midland_Sep2026",
                          "basin": "Midland",
                          "publisher": null,
                          "default": true,
                          "status": "ready",
                          "error": null,
                          "models": {
                            "oil": "M20260930-sample-O-d1",
                            "gas": "M20260930-sample-G-d1",
                            "water": "M20260930-sample-W-d1"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "dataset": "SAMPLE_Midland_Sep2026",
                            "dataset_id": 9001,
                            "build_num": "S20260930"
                          },
                          "pins": null
                        },
                        {
                          "id": "novicast-midland-2610",
                          "label": "Midland 2610",
                          "basin": "Midland",
                          "publisher": "NoviCast",
                          "default": false,
                          "status": "idle",
                          "error": null,
                          "models": {
                            "oil": "M20261014-novicast-O-d1-prod",
                            "gas": "M20261014-novicast-G-d1-prod",
                            "water": "M20261014-novicast-W-d1-prod"
                          },
                          "streams": [
                            "oil",
                            "gas",
                            "water"
                          ],
                          "stream_labels": {},
                          "source": {
                            "customer": "novicast",
                            "dataset_id": 6171,
                            "dataset": "Midland Inventory Update 2610",
                            "build_num": "B20261013-230336"
                          },
                          "pins": {
                            "origin": "fork",
                            "sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
                            "pins": {
                              "manifest_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                              "models": {
                                "oil": "M-O",
                                "gas": "M-G",
                                "water": "M-W"
                              },
                              "depth": {
                                "manifest_sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
                                "versioned": true
                              }
                            },
                            "release": {
                              "sha256": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
                              "differs": {
                                "depth": {
                                  "manifest_sha256": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
                                  "versioned": true
                                }
                              }
                            },
                            "fork_of": {
                              "sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
                              "manifest_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                              "models": {
                                "oil": "M-O",
                                "gas": "M-G",
                                "water": "M-W"
                              },
                              "depth": {
                                "manifest_sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
                                "versioned": true
                              }
                            },
                            "behind": true
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          }
        }
      }
    },
    "/model-sets/{model_set}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ModelSetId"
        }
      ],
      "get": {
        "operationId": "getModelSet",
        "tags": [
          "Service"
        ],
        "summary": "Describe a model set",
        "description": "One model set and its dataset's extent. This loads the set when it isn't loaded yet, so the first call can take a while.\n\n**Includes.** `include` adds what GET /model-sets adds for each set (see the parameter); staff send include=pins for what it is served from.\n\n**What a set is.** A dataset (wells, production, subsurface grids, spacing) with oil, gas and water models, or some of them. `default` is the base dataset; the others are published sets the release file pins, loaded on first use (`status` `idle`, then `loading`) and checked against their manifest. A set that failed to load is `unavailable` with an `error`, and is tried again a minute later.\n\n**Streams.** A set's forecasts, plans, explanations, bands, EUR, type curves and exports carry only its `streams`; BOE counts an unserved oil or gas as 0. Naming another stream (in `decline`, `eur_water`, an export's streams or columns, a type curve, drivers, stats, a wells `sort` or a comparison `metric`) is a 400 `invalid_argument` listing the served ones in `details.allowed`. Economics prices only served streams (condensate in the oil slot at the oil price and differential); on a set serving neither oil nor gas, economics, drivers and ARIES are 400s.\n\n**The default set.** A server may answer requests without `model_set` from a published set (GET /model-sets `default` names it); `model_set=default` still reaches the base dataset. A server may also retire `default`: then it isn't listed, GET /model-sets/default is a 404 and `model_set=default` is a 400 naming the set answering instead.\n\n**Tenant sets.** An environment's own set may be scoped to tenants: staff and those tenants' users see it, and to anyone else it is an unknown id.\n\n**Errors.** A set that can't load is a 503 with the reason. An unknown id is a 404, as is `default` on a server that retired it.",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "description": "Any of these, comma-separated or repeated, each once; any other value is a 400 with details.field include.\n\n- `model_type`: how the set's models were built: causal, standard or null.\n- `facts`: figures about the set's data and models.\n- `catalog`: the set's curated catalog entry, or null.\n- `frame`: the units the set's own data and models are in.\n- `vintage`: the month of the set's build, YYYY-MM, or null.\n- `subsurface_sampling`: where the set's grids are read at a well.\n- `formation_labels`: `grid` when the set's formations come from its own structure grids.\n- `pins` (staff only, else a 403): what the set's entry is served from.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The model set.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelSet"
                },
                "example": {
                  "id": "default",
                  "label": "SAMPLE_Midland_Sep2026",
                  "basin": "Midland",
                  "publisher": null,
                  "default": true,
                  "status": "ready",
                  "error": null,
                  "models": {
                    "oil": "M20260930-sample-O-d1",
                    "gas": "M20260930-sample-G-d1",
                    "water": "M20260930-sample-W-d1"
                  },
                  "streams": [
                    "oil",
                    "gas",
                    "water"
                  ],
                  "stream_labels": {},
                  "source": {
                    "dataset": "SAMPLE_Midland_Sep2026",
                    "dataset_id": 9001,
                    "build_num": "S20260930"
                  },
                  "dataset": {
                    "well_count": 18000,
                    "bbox": [
                      -102.53241,
                      31.15189,
                      -101.22079,
                      32.48628
                    ],
                    "as_of": "2026-09-30",
                    "basin": "Permian",
                    "subbasin": "Midland"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/models": {
      "get": {
        "operationId": "listModels",
        "tags": [
          "Service"
        ],
        "summary": "List the forecast models",
        "description": "The forecast model behind each stream, each as GET /models/{model_num} describes it.\n\n**Includes.** include=groups adds each input's catalog group, include=distribution its training distribution, and include=served_fit_wells the distinct wells the served `all` fit was trained on.\n\n**The card.** What a stream's forecast model is and what it saw.\n\n**Inputs.** `inputs` are the training ranges forecast checks compare against: p01 and p99 over training rows, without the no-neighbor `fill` value. A design input is in `checks.out_of_range` only when it is more than 5% of p99 minus p01 outside them; neighbors' production features (novi_spacing_sum_prior_*, novi_spacing_delgados_p*) outside them, with no margin, go to `checks.context` instead.\n\n**Accuracy.** The served `all` fit was refit on the holdout wells too. Held-out accuracy is the pre-refit `train` fit's (GET /models/{model_num}/evaluation; `evaluation.available` and `reason` say whether there is one), and `holdout.rule` says how holdout wells were chosen. Cached, with an `ETag`; on the sample stack every figure is a sample (`sample_data: true`).",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "description": "`groups`, `distribution` or `served_fit_wells`, comma-separated or repeated, each once; any other value is a 400 with details.field include.\n\n`groups` adds each input's Intel basin report catalog `group`; `distribution` the card's `distribution` and each input's training distribution (five quantiles and a 20-bin histogram, or level counts); `served_fit_wells` the card's count.",
            "schema": {
              "type": "string",
              "enum": [
                "groups",
                "distribution",
                "served_fit_wells",
                "groups,distribution",
                "groups,served_fit_wells",
                "distribution,groups",
                "distribution,served_fit_wells",
                "served_fit_wells,groups",
                "served_fit_wells,distribution",
                "groups,distribution,served_fit_wells",
                "groups,served_fit_wells,distribution",
                "distribution,groups,served_fit_wells",
                "distribution,served_fit_wells,groups",
                "served_fit_wells,groups,distribution",
                "served_fit_wells,distribution,groups"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The models, one per stream.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                },
                "examples": {
                  "all": {
                    "summary": "Models",
                    "value": {
                      "models": [
                        {
                          "model_num": "M20260930-sample-O-d1",
                          "stream": "oil",
                          "target": "novi_oil",
                          "unit": "bbl",
                          "sample_data": true,
                          "served_fit": "all",
                          "trained_on": "training and holdout wells; held-out accuracy is measured on an earlier fit that never saw the holdout wells",
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ],
                          "versions": null,
                          "training": {
                            "wells": 11321,
                            "rows": 407555,
                            "first_production": {
                              "from": "2012-02-24",
                              "to": "2023-05-31"
                            }
                          },
                          "holdout": {
                            "wells": 6233,
                            "rule": "first production on or after 2023-06-01 (the sample's split)",
                            "first_production": {
                              "from": "2023-06-01",
                              "to": "2026-09-01"
                            }
                          },
                          "inputs": [
                            {
                              "feature": "novi_lateral_length",
                              "label": "Lateral length",
                              "kind": "numeric",
                              "p01": 4620,
                              "p99": 15000,
                              "blank_share": 0,
                              "levels": null,
                              "fill": null
                            },
                            {
                              "feature": "novi_formation",
                              "label": "Formation",
                              "kind": "category",
                              "p01": null,
                              "p99": null,
                              "blank_share": 0,
                              "levels": [
                                "DEAN",
                                "JO MILL",
                                "LOWER SPRABERRY SHALE",
                                "MIDDLE SPRABERRY",
                                "WOLFCAMP A",
                                "WOLFCAMP B",
                                "WOLFCAMP C",
                                "WOLFCAMP D"
                              ],
                              "fill": null
                            },
                            {
                              "feature": "novi_spacing_parent_daysonline",
                              "label": "Parent days online",
                              "kind": "numeric",
                              "p01": 222,
                              "p99": 3973,
                              "blank_share": 0,
                              "levels": null,
                              "fill": -1
                            }
                          ],
                          "bands": {
                            "available": true,
                            "method": "Novi's predrill bands (split conformal)",
                            "reason": null
                          },
                          "eur": {
                            "available": true
                          },
                          "evaluation": {
                            "available": true,
                            "reason": null,
                            "href": "/api/v1/models/M20260930-sample-O-d1/evaluation"
                          }
                        }
                      ]
                    }
                  },
                  "distribution": {
                    "summary": "include=distribution",
                    "value": {
                      "models": [
                        {
                          "model_num": "M20260930-sample-O-d1",
                          "stream": "oil",
                          "target": "novi_oil",
                          "unit": "bbl",
                          "sample_data": true,
                          "served_fit": "all",
                          "trained_on": "training and holdout wells; held-out accuracy is measured on an earlier fit that never saw the holdout wells",
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ],
                          "versions": null,
                          "training": {
                            "wells": 11321,
                            "rows": 407555,
                            "first_production": {
                              "from": "2012-02-24",
                              "to": "2023-05-31"
                            }
                          },
                          "holdout": {
                            "wells": 6233,
                            "rule": "first production on or after 2023-06-01 (the sample's split)",
                            "first_production": {
                              "from": "2023-06-01",
                              "to": "2026-09-01"
                            }
                          },
                          "inputs": [
                            {
                              "feature": "novi_lateral_length",
                              "label": "Lateral length",
                              "kind": "numeric",
                              "p01": 4620,
                              "p99": 15000,
                              "blank_share": 0,
                              "levels": null,
                              "fill": null,
                              "distribution": {
                                "unit": "ft",
                                "rows": 407555,
                                "blank": 0,
                                "fill": 0,
                                "ranged": 407555,
                                "min": 4000,
                                "max": 16000,
                                "quantiles": {
                                  "p01": 4620,
                                  "p10": 5573.3,
                                  "p50": 9810,
                                  "p90": 14046.7,
                                  "p99": 15000
                                },
                                "histogram": {
                                  "edges": [
                                    4620,
                                    5139,
                                    5658,
                                    6177,
                                    6696,
                                    7215,
                                    7734,
                                    8253,
                                    8772,
                                    9291,
                                    9810,
                                    10329,
                                    10848,
                                    11367,
                                    11886,
                                    12405,
                                    12924,
                                    13443,
                                    13962,
                                    14481,
                                    15000
                                  ],
                                  "counts": [
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19970,
                                    19975
                                  ],
                                  "below": 4075,
                                  "above": 4075
                                },
                                "levels": null
                              }
                            },
                            {
                              "feature": "novi_formation",
                              "label": "Formation",
                              "kind": "category",
                              "p01": null,
                              "p99": null,
                              "blank_share": 0,
                              "levels": [
                                "DEAN",
                                "JO MILL",
                                "LOWER SPRABERRY SHALE",
                                "MIDDLE SPRABERRY",
                                "WOLFCAMP A",
                                "WOLFCAMP B",
                                "WOLFCAMP C",
                                "WOLFCAMP D"
                              ],
                              "fill": null,
                              "distribution": {
                                "unit": "",
                                "rows": 407555,
                                "blank": 0,
                                "fill": 0,
                                "ranged": 407555,
                                "min": null,
                                "max": null,
                                "quantiles": null,
                                "histogram": null,
                                "levels": [
                                  {
                                    "level": "DEAN",
                                    "rows": 100000
                                  },
                                  {
                                    "level": "JO MILL",
                                    "rows": 90000
                                  },
                                  {
                                    "level": "LOWER SPRABERRY SHALE",
                                    "rows": 80000
                                  },
                                  {
                                    "level": "MIDDLE SPRABERRY",
                                    "rows": 60000
                                  },
                                  {
                                    "level": "WOLFCAMP A",
                                    "rows": 40000
                                  },
                                  {
                                    "level": "WOLFCAMP B",
                                    "rows": 20000
                                  },
                                  {
                                    "level": "WOLFCAMP C",
                                    "rows": 10000
                                  },
                                  {
                                    "level": "WOLFCAMP D",
                                    "rows": 7555
                                  }
                                ]
                              }
                            },
                            {
                              "feature": "novi_spacing_parent_daysonline",
                              "label": "Parent days online",
                              "kind": "numeric",
                              "p01": 222,
                              "p99": 3973,
                              "blank_share": 0,
                              "levels": null,
                              "fill": -1,
                              "distribution": {
                                "unit": "days",
                                "rows": 407555,
                                "blank": 0,
                                "fill": 40000,
                                "ranged": 367555,
                                "min": 0,
                                "max": 4100,
                                "quantiles": {
                                  "p01": 222,
                                  "p10": 566.5,
                                  "p50": 2097.5,
                                  "p90": 3628.5,
                                  "p99": 3973
                                },
                                "histogram": {
                                  "edges": [
                                    222,
                                    409.55,
                                    597.1,
                                    784.65,
                                    972.2,
                                    1159.75,
                                    1347.3,
                                    1534.85,
                                    1722.4,
                                    1909.95,
                                    2097.5,
                                    2285.05,
                                    2472.6,
                                    2660.15,
                                    2847.7,
                                    3035.25,
                                    3222.8,
                                    3410.35,
                                    3597.9,
                                    3785.45,
                                    3973
                                  ],
                                  "counts": [
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18010,
                                    18015
                                  ],
                                  "below": 3675,
                                  "above": 3675
                                },
                                "levels": null
                              }
                            }
                          ],
                          "bands": {
                            "available": true,
                            "method": "Novi's predrill bands (split conformal)",
                            "reason": null
                          },
                          "eur": {
                            "available": true
                          },
                          "evaluation": {
                            "available": true,
                            "reason": null,
                            "href": "/api/v1/models/M20260930-sample-O-d1/evaluation"
                          },
                          "distribution": {
                            "available": true,
                            "reason": null
                          }
                        }
                      ]
                    }
                  },
                  "groups": {
                    "summary": "include=groups",
                    "value": {
                      "models": [
                        {
                          "model_num": "M20260930-sample-O-d1",
                          "stream": "oil",
                          "target": "novi_oil",
                          "unit": "bbl",
                          "sample_data": true,
                          "served_fit": "all",
                          "trained_on": "training and holdout wells; held-out accuracy is measured on an earlier fit that never saw the holdout wells",
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ],
                          "versions": null,
                          "training": {
                            "wells": 11321,
                            "rows": 407555,
                            "first_production": {
                              "from": "2012-02-24",
                              "to": "2023-05-31"
                            }
                          },
                          "holdout": {
                            "wells": 6233,
                            "rule": "first production on or after 2023-06-01 (the sample's split)",
                            "first_production": {
                              "from": "2023-06-01",
                              "to": "2026-09-01"
                            }
                          },
                          "inputs": [
                            {
                              "feature": "novi_lateral_length",
                              "label": "Lateral length",
                              "kind": "numeric",
                              "p01": 4620,
                              "p99": 15000,
                              "blank_share": 0,
                              "levels": null,
                              "fill": null,
                              "group": "completion"
                            },
                            {
                              "feature": "novi_formation",
                              "label": "Formation",
                              "kind": "category",
                              "p01": null,
                              "p99": null,
                              "blank_share": 0,
                              "levels": [
                                "DEAN",
                                "JO MILL",
                                "LOWER SPRABERRY SHALE",
                                "MIDDLE SPRABERRY",
                                "WOLFCAMP A",
                                "WOLFCAMP B",
                                "WOLFCAMP C",
                                "WOLFCAMP D"
                              ],
                              "fill": null,
                              "group": "geology"
                            },
                            {
                              "feature": "novi_spacing_parent_daysonline",
                              "label": "Parent days online",
                              "kind": "numeric",
                              "p01": 222,
                              "p99": 3973,
                              "blank_share": 0,
                              "levels": null,
                              "fill": -1,
                              "group": "spacing"
                            }
                          ],
                          "bands": {
                            "available": true,
                            "method": "Novi's predrill bands (split conformal)",
                            "reason": null
                          },
                          "eur": {
                            "available": true
                          },
                          "evaluation": {
                            "available": true,
                            "reason": null,
                            "href": "/api/v1/models/M20260930-sample-O-d1/evaluation"
                          }
                        }
                      ]
                    }
                  },
                  "served_fit_wells": {
                    "summary": "include=served_fit_wells",
                    "value": {
                      "models": [
                        {
                          "model_num": "M20260930-sample-O-d1",
                          "stream": "oil",
                          "target": "novi_oil",
                          "unit": "bbl",
                          "sample_data": true,
                          "served_fit": "all",
                          "served_fit_wells": 17554,
                          "trained_on": "training and holdout wells; held-out accuracy is measured on an earlier fit that never saw the holdout wells",
                          "ip_days": [
                            30,
                            60,
                            90,
                            1080
                          ],
                          "versions": null,
                          "training": {
                            "wells": 11321,
                            "rows": 407555,
                            "first_production": {
                              "from": "2012-02-24",
                              "to": "2023-05-31"
                            }
                          },
                          "holdout": {
                            "wells": 6233,
                            "rule": "first production on or after 2023-06-01 (the sample's split)",
                            "first_production": {
                              "from": "2023-06-01",
                              "to": "2026-09-01"
                            }
                          },
                          "inputs": [
                            {
                              "feature": "novi_lateral_length",
                              "label": "Lateral length",
                              "kind": "numeric",
                              "p01": 4620,
                              "p99": 15000,
                              "blank_share": 0,
                              "levels": null,
                              "fill": null
                            },
                            {
                              "feature": "novi_formation",
                              "label": "Formation",
                              "kind": "category",
                              "p01": null,
                              "p99": null,
                              "blank_share": 0,
                              "levels": [
                                "DEAN",
                                "JO MILL",
                                "LOWER SPRABERRY SHALE",
                                "MIDDLE SPRABERRY",
                                "WOLFCAMP A",
                                "WOLFCAMP B",
                                "WOLFCAMP C",
                                "WOLFCAMP D"
                              ],
                              "fill": null
                            },
                            {
                              "feature": "novi_spacing_parent_daysonline",
                              "label": "Parent days online",
                              "kind": "numeric",
                              "p01": 222,
                              "p99": 3973,
                              "blank_share": 0,
                              "levels": null,
                              "fill": -1
                            }
                          ],
                          "bands": {
                            "available": true,
                            "method": "Novi's predrill bands (split conformal)",
                            "reason": null
                          },
                          "eur": {
                            "available": true
                          },
                          "evaluation": {
                            "available": true,
                            "reason": null,
                            "href": "/api/v1/models/M20260930-sample-O-d1/evaluation"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/models/{model_num}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ModelNum"
        }
      ],
      "get": {
        "operationId": "getModel",
        "tags": [
          "Service"
        ],
        "summary": "Describe a forecast model",
        "description": "One stream's forecast model, as GET /models lists it.\n\n**The card.** What a stream's forecast model is and what it saw.\n\n**Inputs.** `inputs` are the training ranges forecast checks compare against: p01 and p99 over training rows, without the no-neighbor `fill` value. A design input is in `checks.out_of_range` only when it is more than 5% of p99 minus p01 outside them; neighbors' production features (novi_spacing_sum_prior_*, novi_spacing_delgados_p*) outside them, with no margin, go to `checks.context` instead.\n\n**Accuracy.** The served `all` fit was refit on the holdout wells too. Held-out accuracy is the pre-refit `train` fit's (GET /models/{model_num}/evaluation; `evaluation.available` and `reason` say whether there is one), and `holdout.rule` says how holdout wells were chosen. Cached, with an `ETag`; on the sample stack every figure is a sample (`sample_data: true`).\n\n**Includes.** include=groups adds each input's catalog group, include=distribution its training distribution, and include=served_fit_wells the distinct wells the served `all` fit was trained on.\n\n**Errors.** An unknown model number is a 404.",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "description": "`groups`, `distribution` or `served_fit_wells`, comma-separated or repeated, each once; any other value is a 400 with details.field include.\n\n`groups` adds each input's Intel basin report catalog `group`; `distribution` the card's `distribution` and each input's training distribution (five quantiles and a 20-bin histogram, or level counts); `served_fit_wells` the card's count.",
            "schema": {
              "type": "string",
              "enum": [
                "groups",
                "distribution",
                "served_fit_wells",
                "groups,distribution",
                "groups,served_fit_wells",
                "distribution,groups",
                "distribution,served_fit_wells",
                "served_fit_wells,groups",
                "served_fit_wells,distribution",
                "groups,distribution,served_fit_wells",
                "groups,served_fit_wells,distribution",
                "distribution,groups,served_fit_wells",
                "distribution,served_fit_wells,groups",
                "served_fit_wells,groups,distribution",
                "served_fit_wells,distribution,groups"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The model's card.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelCard"
                },
                "examples": {
                  "card": {
                    "summary": "Model card",
                    "value": {
                      "model_num": "M20260930-sample-O-d1",
                      "stream": "oil",
                      "target": "novi_oil",
                      "unit": "bbl",
                      "sample_data": true,
                      "served_fit": "all",
                      "trained_on": "training and holdout wells; held-out accuracy is measured on an earlier fit that never saw the holdout wells",
                      "ip_days": [
                        30,
                        60,
                        90,
                        1080
                      ],
                      "versions": null,
                      "training": {
                        "wells": 11321,
                        "rows": 407555,
                        "first_production": {
                          "from": "2012-02-24",
                          "to": "2023-05-31"
                        }
                      },
                      "holdout": {
                        "wells": 6233,
                        "rule": "first production on or after 2023-06-01 (the sample's split)",
                        "first_production": {
                          "from": "2023-06-01",
                          "to": "2026-09-01"
                        }
                      },
                      "inputs": [
                        {
                          "feature": "novi_lateral_length",
                          "label": "Lateral length",
                          "kind": "numeric",
                          "p01": 4620,
                          "p99": 15000,
                          "blank_share": 0,
                          "levels": null,
                          "fill": null
                        },
                        {
                          "feature": "novi_formation",
                          "label": "Formation",
                          "kind": "category",
                          "p01": null,
                          "p99": null,
                          "blank_share": 0,
                          "levels": [
                            "DEAN",
                            "JO MILL",
                            "LOWER SPRABERRY SHALE",
                            "MIDDLE SPRABERRY",
                            "WOLFCAMP A",
                            "WOLFCAMP B",
                            "WOLFCAMP C",
                            "WOLFCAMP D"
                          ],
                          "fill": null
                        },
                        {
                          "feature": "novi_spacing_parent_daysonline",
                          "label": "Parent days online",
                          "kind": "numeric",
                          "p01": 222,
                          "p99": 3973,
                          "blank_share": 0,
                          "levels": null,
                          "fill": -1
                        }
                      ],
                      "bands": {
                        "available": true,
                        "method": "Novi's predrill bands (split conformal)",
                        "reason": null
                      },
                      "eur": {
                        "available": true
                      },
                      "evaluation": {
                        "available": true,
                        "reason": null,
                        "href": "/api/v1/models/M20260930-sample-O-d1/evaluation"
                      }
                    }
                  },
                  "distribution": {
                    "summary": "include=distribution",
                    "value": {
                      "model_num": "M20260930-sample-O-d1",
                      "stream": "oil",
                      "target": "novi_oil",
                      "unit": "bbl",
                      "sample_data": true,
                      "served_fit": "all",
                      "trained_on": "training and holdout wells; held-out accuracy is measured on an earlier fit that never saw the holdout wells",
                      "ip_days": [
                        30,
                        60,
                        90,
                        1080
                      ],
                      "versions": null,
                      "training": {
                        "wells": 11321,
                        "rows": 407555,
                        "first_production": {
                          "from": "2012-02-24",
                          "to": "2023-05-31"
                        }
                      },
                      "holdout": {
                        "wells": 6233,
                        "rule": "first production on or after 2023-06-01 (the sample's split)",
                        "first_production": {
                          "from": "2023-06-01",
                          "to": "2026-09-01"
                        }
                      },
                      "inputs": [
                        {
                          "feature": "novi_lateral_length",
                          "label": "Lateral length",
                          "kind": "numeric",
                          "p01": 4620,
                          "p99": 15000,
                          "blank_share": 0,
                          "levels": null,
                          "fill": null,
                          "distribution": {
                            "unit": "ft",
                            "rows": 407555,
                            "blank": 0,
                            "fill": 0,
                            "ranged": 407555,
                            "min": 4000,
                            "max": 16000,
                            "quantiles": {
                              "p01": 4620,
                              "p10": 5573.3,
                              "p50": 9810,
                              "p90": 14046.7,
                              "p99": 15000
                            },
                            "histogram": {
                              "edges": [
                                4620,
                                5139,
                                5658,
                                6177,
                                6696,
                                7215,
                                7734,
                                8253,
                                8772,
                                9291,
                                9810,
                                10329,
                                10848,
                                11367,
                                11886,
                                12405,
                                12924,
                                13443,
                                13962,
                                14481,
                                15000
                              ],
                              "counts": [
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19970,
                                19975
                              ],
                              "below": 4075,
                              "above": 4075
                            },
                            "levels": null
                          }
                        },
                        {
                          "feature": "novi_formation",
                          "label": "Formation",
                          "kind": "category",
                          "p01": null,
                          "p99": null,
                          "blank_share": 0,
                          "levels": [
                            "DEAN",
                            "JO MILL",
                            "LOWER SPRABERRY SHALE",
                            "MIDDLE SPRABERRY",
                            "WOLFCAMP A",
                            "WOLFCAMP B",
                            "WOLFCAMP C",
                            "WOLFCAMP D"
                          ],
                          "fill": null,
                          "distribution": {
                            "unit": "",
                            "rows": 407555,
                            "blank": 0,
                            "fill": 0,
                            "ranged": 407555,
                            "min": null,
                            "max": null,
                            "quantiles": null,
                            "histogram": null,
                            "levels": [
                              {
                                "level": "DEAN",
                                "rows": 100000
                              },
                              {
                                "level": "JO MILL",
                                "rows": 90000
                              },
                              {
                                "level": "LOWER SPRABERRY SHALE",
                                "rows": 80000
                              },
                              {
                                "level": "MIDDLE SPRABERRY",
                                "rows": 60000
                              },
                              {
                                "level": "WOLFCAMP A",
                                "rows": 40000
                              },
                              {
                                "level": "WOLFCAMP B",
                                "rows": 20000
                              },
                              {
                                "level": "WOLFCAMP C",
                                "rows": 10000
                              },
                              {
                                "level": "WOLFCAMP D",
                                "rows": 7555
                              }
                            ]
                          }
                        },
                        {
                          "feature": "novi_spacing_parent_daysonline",
                          "label": "Parent days online",
                          "kind": "numeric",
                          "p01": 222,
                          "p99": 3973,
                          "blank_share": 0,
                          "levels": null,
                          "fill": -1,
                          "distribution": {
                            "unit": "days",
                            "rows": 407555,
                            "blank": 0,
                            "fill": 40000,
                            "ranged": 367555,
                            "min": 0,
                            "max": 4100,
                            "quantiles": {
                              "p01": 222,
                              "p10": 566.5,
                              "p50": 2097.5,
                              "p90": 3628.5,
                              "p99": 3973
                            },
                            "histogram": {
                              "edges": [
                                222,
                                409.55,
                                597.1,
                                784.65,
                                972.2,
                                1159.75,
                                1347.3,
                                1534.85,
                                1722.4,
                                1909.95,
                                2097.5,
                                2285.05,
                                2472.6,
                                2660.15,
                                2847.7,
                                3035.25,
                                3222.8,
                                3410.35,
                                3597.9,
                                3785.45,
                                3973
                              ],
                              "counts": [
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18010,
                                18015
                              ],
                              "below": 3675,
                              "above": 3675
                            },
                            "levels": null
                          }
                        }
                      ],
                      "bands": {
                        "available": true,
                        "method": "Novi's predrill bands (split conformal)",
                        "reason": null
                      },
                      "eur": {
                        "available": true
                      },
                      "evaluation": {
                        "available": true,
                        "reason": null,
                        "href": "/api/v1/models/M20260930-sample-O-d1/evaluation"
                      },
                      "distribution": {
                        "available": true,
                        "reason": null
                      }
                    }
                  },
                  "served_fit_wells": {
                    "summary": "include=served_fit_wells",
                    "value": {
                      "model_num": "M20260930-sample-O-d1",
                      "stream": "oil",
                      "target": "novi_oil",
                      "unit": "bbl",
                      "sample_data": true,
                      "served_fit": "all",
                      "served_fit_wells": 17554,
                      "trained_on": "training and holdout wells; held-out accuracy is measured on an earlier fit that never saw the holdout wells",
                      "ip_days": [
                        30,
                        60,
                        90,
                        1080
                      ],
                      "versions": null,
                      "training": {
                        "wells": 11321,
                        "rows": 407555,
                        "first_production": {
                          "from": "2012-02-24",
                          "to": "2023-05-31"
                        }
                      },
                      "holdout": {
                        "wells": 6233,
                        "rule": "first production on or after 2023-06-01 (the sample's split)",
                        "first_production": {
                          "from": "2023-06-01",
                          "to": "2026-09-01"
                        }
                      },
                      "inputs": [
                        {
                          "feature": "novi_lateral_length",
                          "label": "Lateral length",
                          "kind": "numeric",
                          "p01": 4620,
                          "p99": 15000,
                          "blank_share": 0,
                          "levels": null,
                          "fill": null
                        },
                        {
                          "feature": "novi_formation",
                          "label": "Formation",
                          "kind": "category",
                          "p01": null,
                          "p99": null,
                          "blank_share": 0,
                          "levels": [
                            "DEAN",
                            "JO MILL",
                            "LOWER SPRABERRY SHALE",
                            "MIDDLE SPRABERRY",
                            "WOLFCAMP A",
                            "WOLFCAMP B",
                            "WOLFCAMP C",
                            "WOLFCAMP D"
                          ],
                          "fill": null
                        },
                        {
                          "feature": "novi_spacing_parent_daysonline",
                          "label": "Parent days online",
                          "kind": "numeric",
                          "p01": 222,
                          "p99": 3973,
                          "blank_share": 0,
                          "levels": null,
                          "fill": -1
                        }
                      ],
                      "bands": {
                        "available": true,
                        "method": "Novi's predrill bands (split conformal)",
                        "reason": null
                      },
                      "eur": {
                        "available": true
                      },
                      "evaluation": {
                        "available": true,
                        "reason": null,
                        "href": "/api/v1/models/M20260930-sample-O-d1/evaluation"
                      }
                    }
                  }
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/models/{model_num}/evaluation": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ModelNum"
        }
      ],
      "get": {
        "operationId": "getModelEvaluation",
        "tags": [
          "Service"
        ],
        "summary": "Measure a model's accuracy on held-out wells",
        "description": "Accuracy of the pre-refit `train` fit on wells it never saw (`split=holdout`, the default): its stored prediction against each well's actual cumulative at each ip_day.\n\n**The fit measured.** The `all` fit that serves forecasts was refit on these wells, so the figures describe the model before that refit. `split=train` measures it on its own training wells: in-sample, so the error reads better; label it so. On the sample stack, sample numbers.\n\n**Metrics.** Each row covers the wells that reached the ip_day with an actual above 0 and a stored prediction (`wells`); under `min_wells` (5) the metrics are null. Long horizons rest on the earliest holdout wells.\n\n- `mdape`: median |predicted − actual| / actual. `median_ratio`: median predicted / actual.\n- `within_10`, `within_25`: the share with |predicted / actual − 1| at most 10% or 25%. `bias`: median predicted / actual − 1.\n- `correlation`: Pearson's r of predicted and actual.\n\n**Options.** `group_by` splits by formation or first-production year; `ip_day` keeps one row, and with it `include=wells` adds that row's wells with their predicted and actual cumulative and APE. `near` (with `radius_mi`) or `bbox` keeps the split's wells in that area, by lateral midpoint, and `scope` echoes it with its wells' count; an area without any answers `groups: []` with `scope.wells` 0.\n\n**Errors.** 503 when this dataset has no stored predictions (GET /models/{model_num} `evaluation.reason` says why).",
        "parameters": [
          {
            "name": "split",
            "in": "query",
            "description": "holdout: wells the train fit never saw; train: its own training wells (in-sample).",
            "schema": {
              "type": "string",
              "enum": [
                "holdout",
                "train"
              ],
              "default": "holdout"
            }
          },
          {
            "name": "group_by",
            "in": "query",
            "description": "none: one group of every well; formation or first_year: one group each, formations in GET /formations order, years oldest first.",
            "schema": {
              "type": "string",
              "enum": [
                "none",
                "formation",
                "first_year"
              ],
              "default": "none"
            }
          },
          {
            "name": "ip_day",
            "in": "query",
            "description": "Only this ip_day's row in each group: one of the model's ip_days (400 otherwise, with them in `details.allowed`). Without it, every ip_day.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "include",
            "in": "query",
            "description": "`wells` adds the wells behind that ip_day's metrics, each with its predicted and actual cumulative and APE, for a predicted-against-actual scatter or a residual plot. It needs `ip_day` (400 without it).\n\n- Exactly the metrics' population: the split's wells with a stored prediction and an actual above 0 at that ip_day, by formation (name order, none last) then key; with `group_by`, each with its `group`.\n- At most 10,000 wells: a larger population is a 400 with `details.max` and `details.count`, never a cut list. The sample's oil model at 360 days has 4,353 holdout wells, about 540 KB (73 KB gzipped).",
            "schema": {
              "type": "string",
              "enum": [
                "wells"
              ]
            }
          },
          {
            "name": "near",
            "in": "query",
            "description": "Only the split's wells within `radius_mi` of this point: `lng,lat` in degrees, matched as GET /wells `near` matches wells, by great-circle miles to each lateral's midpoint. Every row and `include=wells` cover those wells only, and `scope` echoes the area with its `wells`. A small area has few wells, so its cells may have null metrics (under `min_wells`). Send `near` or `bbox`, not both (400).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "radius_mi",
            "in": "query",
            "description": "With `near` (400 without it): how far from it, in miles, a decimal greater than 0 and at most 100 written as digits (2 or 2.5); default 5.",
            "schema": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 100,
              "default": 5
            }
          },
          {
            "name": "bbox",
            "in": "query",
            "description": "Only the split's wells whose lateral midpoint is inside `west,south,east,north` (degrees), as GET /wells `bbox` filters wells. Every row and `include=wells` cover those wells only, and `scope` echoes the box with its `wells`. Send `near` or `bbox`, not both (400).",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The evaluation.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelEvaluation"
                },
                "example": {
                  "model_num": "M20260930-sample-O-d1",
                  "sample_data": true,
                  "fit": "train",
                  "split": "holdout",
                  "rule": "first production on or after 2023-06-01 (the sample's split)",
                  "as_of": "2026-09-30",
                  "min_wells": 5,
                  "group_by": "none",
                  "groups": [
                    {
                      "group": null,
                      "rows": [
                        {
                          "ip_day": 360,
                          "wells": 4353,
                          "mdape": 0.144,
                          "median_ratio": 1.0272,
                          "within_10": 0.3611,
                          "within_25": 0.7749,
                          "bias": 0.0272,
                          "correlation": 0.8655
                        },
                        {
                          "ip_day": 720,
                          "wells": 2659,
                          "mdape": 0.1458,
                          "median_ratio": 1.0239,
                          "within_10": 0.3595,
                          "within_25": 0.7706,
                          "bias": 0.0239,
                          "correlation": 0.8647
                        },
                        {
                          "ip_day": 1080,
                          "wells": 950,
                          "mdape": 0.1426,
                          "median_ratio": 1.0283,
                          "within_10": 0.3674,
                          "within_25": 0.78,
                          "bias": 0.0283,
                          "correlation": 0.856
                        }
                      ]
                    }
                  ]
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/models/{model_num}/baselines": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ModelNum"
        }
      ],
      "get": {
        "operationId": "getModelBaselines",
        "tags": [
          "Service"
        ],
        "summary": "Get a model's SHAP baselines",
        "description": "The references `compare` rebases explanations onto, per ip_day: each formation's wells (`formation`) and all of them (`dataset`). Use it for a formation × feature heatmap, or to say what typically drives a formation without a well.\n\n**What comes back.** `expected_value` is the wells' mean expected value, `values` each feature's mean SHAP contribution, and `value` their sum (the mean forecast only where SHAP is additive); null and empty under `min_wells` wells. `wells` counts them per ip_day; long ip_days rest on older wells.\n\n**Options.** `formation` keeps those formations (`dataset` always comes back); `ip_day` keeps one row.\n\n**Errors.** 503 when this dataset has no baselines. On the sample stack, sample numbers.",
        "parameters": [
          {
            "name": "formation",
            "in": "query",
            "description": "Only these formations' baselines: one name or a comma-separated list, case-insensitive. The dataset reference always comes back.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ip_day",
            "in": "query",
            "description": "Only this ip_day's row: one of the model's ip_days (400 otherwise, with them in `details.allowed`). Without it, every ip_day.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "$ref": "#/components/parameters/ModelSet"
          }
        ],
        "responses": {
          "200": {
            "description": "The baselines.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelBaselines"
                },
                "example": {
                  "model_num": "M20260930-sample-O-d1",
                  "sample_data": true,
                  "unit": "bbl",
                  "source": "mean SHAP over a seeded sample of 60 producing wells per formation (sample data), per ip_day",
                  "min_wells": 5,
                  "baselines": [
                    {
                      "reference": "formation",
                      "formation": "WOLFCAMP A",
                      "label": "Typical Wolfcamp A well",
                      "rows": [
                        {
                          "ip_day": 360,
                          "wells": 53,
                          "expected_value": 241814.903,
                          "value": 175650.75,
                          "values": {
                            "novi_lateral_length": -40049.918,
                            "novi_spacing_lateralcloser_mintangent": -12567.325,
                            "novi_spacing_staggercloser_mintangent": -4825.188
                          }
                        }
                      ]
                    },
                    {
                      "reference": "dataset",
                      "formation": null,
                      "label": "Typical well in the dataset",
                      "rows": [
                        {
                          "ip_day": 360,
                          "wells": 421,
                          "expected_value": 241814.903,
                          "value": 135190.854,
                          "values": {
                            "novi_formation": -34223.99,
                            "novi_lateral_length": -30840.371,
                            "novi_bvi_avg": -10818.849
                          }
                        }
                      ]
                    }
                  ]
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/Internal"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "WellKey": {
        "name": "key",
        "in": "path",
        "required": true,
        "description": "Wellbore key, as SB329-01414. GET /wells/facets, /wells/search, /wells/typecurve and /wells/production are paths, not wells: keys are API numbers or SBnnn-nnnnn, so no well is shadowed.",
        "schema": {
          "type": "string"
        },
        "example": "SB329-01414"
      },
      "ModelSet": {
        "name": "model_set",
        "in": "query",
        "description": "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.\n\n- `model_set=default` reaches the base dataset; once the server retires it, a 400 naming the set answering instead.\n- 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.\n- 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`.\n- An explicit `model_set` wins; naming resources of two sets in one request is a 400.",
        "schema": {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
        }
      },
      "ModelSetId": {
        "name": "model_set",
        "in": "path",
        "required": true,
        "description": "A model set's id, from GET /model-sets; `default` unless the server retired it.",
        "schema": {
          "type": "string",
          "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
        },
        "example": "default"
      },
      "ModelNum": {
        "name": "model_num",
        "in": "path",
        "required": true,
        "description": "Model number, from GET /models or GET /dataset `models[].model_num`.",
        "schema": {
          "type": "string"
        },
        "example": "M20260930-sample-O-d1"
      },
      "SavedCollection": {
        "name": "collection",
        "in": "path",
        "required": true,
        "description": "Saved document collection; any other name is 400. assumption-sets takes a typed body, AssumptionSetBody; column-mappings takes { column_hints, formations? }. plan-views takes a PlanViewBody, checked as GET /plans checks its parameters.",
        "schema": {
          "type": "string",
          "enum": [
            "filter-sets",
            "completion-designs",
            "type-curves",
            "views",
            "settings",
            "assumption-sets",
            "column-mappings",
            "plan-views"
          ]
        }
      },
      "PlanId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Plan id from POST /plans.",
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "example": "9cae6c80-cbd7-4339-b1c0-1cac810d0630"
      },
      "ExportId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "Export id from POST /exports.",
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "example": "8b8369bd-2c32-4213-8261-f8666e94598c"
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "description": "Page to read: `next_cursor` from the previous page.",
        "schema": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Makes a retry safe: send your own key (a UUID, or your request id) and the same key on every retry. Without the header, nothing changes.\n\nThe same key and body (compared as JSON, key order ignored) within 24 hours replays what the first request made, with its id, in its current state, with `Idempotent-Replayed: true`, and starts nothing. A different body is a 409 (`details.field` `Idempotency-Key`).\n\n- Keys are per operation, and only a success records one: retry a 502, 503, 504 or a lost response with the same key.\n- With Redis, POST /saved/{collection}, /forecast-sources and /area-sets keep keys there, as do POST /plans and /exports on a server with a state store: every server task shares them and a restart keeps them. While Redis isn't answering, these answer 503.\n  - A retry while the first request is still being made waits up to 30 s for it, then answers 409: retry shortly with the same key.\n  - A key the first request hasn't recorded within a minute (its task stopped, or Redis failed as it finished) lapses; a retry then makes the resource again.\n- Otherwise keys live in the server process's memory, the latest 1,000 per operation: a restart (a deploy is one) forgets them, and a retry during the first request waits for it.\n- POST /forecasts with `async: true` and POST /plans/{id}/economics keep each key with its job, as their descriptions say. A POST /plans with `dry_run: true` neither keeps nor replays its key.\n- A replay of a plan or export the server has dropped is a 404.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._:-]{1,128}$"
        },
        "example": "mcp-start_plan-0b9f2c4e-7d1a-4e3b-9c5f-2a8d6e1f4b70"
      }
    },
    "headers": {
      "RequestId": {
        "description": "Request id: yours if you sent one, else generated. Quote it when reporting a problem.",
        "schema": {
          "type": "string"
        }
      },
      "ETag": {
        "description": "Validator for If-None-Match; on plan reads, only once the plan is done or failed, with Cache-Control: private, no-cache, so a browser keeps the answer and revalidates it.",
        "schema": {
          "type": "string"
        }
      },
      "VersionETag": {
        "description": "The resource's version. Send it as If-Match on the PUT or PATCH that changes the resource (409 with details.etag when it is stale). It is not an If-None-Match validator: the read answers 200 with the full body.",
        "schema": {
          "type": "string"
        }
      },
      "CacheControl": {
        "description": "public, max-age=600 on cacheable reads (cache for 10 minutes), private, max-age=600 on a model set scoped to tenants; private, no-cache on plan reads with an ETag (a browser keeps them and revalidates); no-store otherwise.",
        "schema": {
          "type": "string"
        }
      },
      "Location": {
        "description": "URL of the new plan or export.",
        "schema": {
          "type": "string",
          "format": "uri-reference"
        }
      },
      "RetryAfter": {
        "description": "Seconds to wait before polling again.",
        "schema": {
          "type": "integer"
        }
      },
      "IdempotentReplayed": {
        "description": "true: this response replays the first request with the same Idempotency-Key, and nothing new was started. Absent otherwise.",
        "schema": {
          "type": "string",
          "enum": [
            "true"
          ]
        }
      },
      "ContentDisposition": {
        "description": "attachment; filename=\"plan-<wells>-wells-<date>.zip\"",
        "schema": {
          "type": "string"
        }
      },
      "AnalogsContentDisposition": {
        "description": "With format=csv only: attachment; filename=\"plan-well-<n>-design-<m>-analogs-<YYYY-MM-DD>.csv\", n and m counted from 1.",
        "schema": {
          "type": "string"
        }
      },
      "ExportContentDisposition": {
        "description": "attachment, with the file name in ASCII (filename: letters, digits, dots, dashes and underscores, anything else as -) and exactly (filename*, UTF-8).",
        "schema": {
          "type": "string"
        }
      },
      "FileETag": {
        "description": "Strong validator: \"sha256-\" and the first 22 base64url characters of the file's SHA-256. Send it as If-None-Match (304) or If-Range (resume).",
        "schema": {
          "type": "string"
        }
      },
      "ContentLength": {
        "description": "Bytes in the body: the whole file, or the range.",
        "schema": {
          "type": "integer"
        }
      },
      "AcceptRanges": {
        "description": "bytes: the file can be read in ranges.",
        "schema": {
          "type": "string",
          "enum": [
            "bytes"
          ]
        }
      },
      "ContentRange": {
        "description": "The bytes sent and the file's size, as bytes 0-1023/52311.",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "NotModified": {
        "description": "Unchanged since the ETag in If-None-Match.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "ETag": {
            "$ref": "#/components/headers/ETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        }
      },
      "Unauthenticated": {
        "description": "No valid token. Novi's sign-in layer answers `{\"code\": 401, \"message\": \"Unauthorized\"}` when the bearer token is missing, expired or revoked.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Your account lacks the Access Forecasts permission; `code` is `invalid_argument`.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "BadRequest": {
        "description": "An input is invalid; `details.field` names it.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "invalid_argument",
                "message": "wells[0].tvd isn't a known field; did you mean tvd_ft?",
                "details": {
                  "field": "wells[0].tvd"
                }
              },
              "request_id": "3c9d1e7a-2b4f-4a6c-9d8e-7f1a2b3c4d5e"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such well, grid, plan or route.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Well SB999-00000 not found",
                "details": {
                  "key": "SB999-00000"
                }
              },
              "request_id": "3c9d1e7a-2b4f-4a6c-9d8e-7f1a2b3c4d5e"
            }
          }
        }
      },
      "Conflict": {
        "description": "The request conflicts with the state of the plan or resource it names, and `message` says how: for example a plan still running or failed, a stale `If-Match`, an `Idempotency-Key` reused with another body, or a server without a state store.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "conflict",
                "message": "Plan 9cae6c80-cbd7-4339-b1c0-1cac810d0630 is still running; wait for status done",
                "details": {
                  "id": "9cae6c80-cbd7-4339-b1c0-1cac810d0630",
                  "status": "running"
                }
              },
              "request_id": "6f1c2b9e-3d4a-4f0e-9b8c-2a7d5e1f0c3b"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "The request body is over 10 MB.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Gone": {
        "description": "The export expired, and its file was removed; create the export again.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "Export 8b8369bd-2c32-4213-8261-f8666e94598c expired, and its file was removed to keep within the server's retention; create it again with POST /api/v1/exports",
                "details": {
                  "id": "8b8369bd-2c32-4213-8261-f8666e94598c",
                  "status": "expired"
                }
              },
              "request_id": "4b8d2f60-1c7e-4a39-9e5b-3f0c6a8d2e17"
            }
          }
        }
      },
      "RangeNotSatisfiable": {
        "description": "The range starts past the end of the file.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Content-Range": {
            "description": "bytes */<size>: the file's size.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "WorkerFailed": {
        "description": "A model worker returned an error.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unavailable": {
        "description": "A model worker or the subsurface grids aren't ready; retry shortly.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "unavailable",
                "message": "The spacing model worker isn't running; retry shortly, and ask your Novi admin if it persists",
                "details": {
                  "worker": "spacing"
                }
              },
              "request_id": "0b5e8f2a-7c1d-4e6b-a3f9-5d2c8e4b1a70"
            }
          }
        }
      },
      "Internal": {
        "description": "Unexpected server error.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/RequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "internal",
                "message": "Internal error; quote request id 9a4c7e21-5b3f-4d8a-8e6c-1f2b3a4d5c6e when reporting it",
                "details": {}
              },
              "request_id": "9a4c7e21-5b3f-4d8a-8e6c-1f2b3a4d5c6e"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Error envelope.",
        "required": [
          "error",
          "request_id"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorBody"
          },
          "request_id": {
            "type": "string",
            "description": "The X-Request-Id of the failed request."
          }
        },
        "additionalProperties": false
      },
      "ErrorBody": {
        "type": "object",
        "description": "The error.",
        "required": [
          "code",
          "message",
          "details"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Machine-readable code.",
            "enum": [
              "invalid_argument",
              "not_found",
              "conflict",
              "unavailable",
              "internal"
            ]
          },
          "message": {
            "type": "string",
            "description": "What went wrong and how to fix it."
          },
          "details": {
            "type": "object",
            "description": "Context: `field` names the input at fault, as wells[3].tvd_ft.",
            "properties": {
              "field": {
                "type": "string",
                "description": "The input at fault."
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": false
      },
      "LngLat": {
        "type": "array",
        "description": "A point as [longitude, latitude] in WGS 84 degrees.",
        "prefixItems": [
          {
            "type": "number",
            "description": "Longitude",
            "minimum": -180,
            "maximum": 180
          },
          {
            "type": "number",
            "description": "Latitude",
            "minimum": -90,
            "maximum": 90
          }
        ],
        "minItems": 2,
        "maxItems": 2,
        "items": false
      },
      "ModelSetFacts": {
        "type": "object",
        "description": "Figures about a set's data and models, computed once after the set loads, best effort.",
        "required": [
          "well_count",
          "training_wells",
          "holdout_wells",
          "formation_count",
          "target_zone_count",
          "as_of",
          "forecast_days",
          "feature_count"
        ],
        "properties": {
          "well_count": {
            "type": "integer",
            "description": "The set's wells, as GET /dataset well_count."
          },
          "training_wells": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Distinct wells in the train split of the set's stored model predictions, as GET /models/{model_num}/evaluation splits them; null when the set stores none for that split."
          },
          "holdout_wells": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Distinct wells in the holdout split of the set's stored model predictions, as GET /models/{model_num}/evaluation splits them; null when the set stores none for that split."
          },
          "formation_count": {
            "type": "integer",
            "description": "Formations with wells or grids, as GET /formations lists them."
          },
          "target_zone_count": {
            "type": "integer",
            "description": "Formations GET /formations?include=target marks target."
          },
          "as_of": {
            "type": [
              "string",
              "null"
            ],
            "description": "Latest production date, as GET /dataset as_of.",
            "format": "date"
          },
          "forecast_days": {
            "type": "integer",
            "description": "The largest ip_day any of the set's served models forecasts (GET /models `ip_days`); GET /dataset ip_days when the models aren't listed."
          },
          "feature_count": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Distinct input features across the set's oil, gas and water models; null when the server doesn't know its models' features."
          }
        },
        "additionalProperties": false
      },
      "StreamAccuracy": {
        "type": "object",
        "description": "Published stream accuracy from the catalog, expressed as fractions.",
        "required": [
          "mape_ip90",
          "mape_ip1080",
          "ape_ip90",
          "ape_ip1080"
        ],
        "properties": {
          "mape_ip90": {
            "type": [
              "number",
              "null"
            ],
            "description": "The catalog's MAPE at IP90, as a fraction (0.172 is 17.2%); null when the catalog doesn't report it.",
            "minimum": 0
          },
          "mape_ip1080": {
            "type": [
              "number",
              "null"
            ],
            "description": "The catalog's MAPE at IP1080, as a fraction; null when the catalog doesn't report it.",
            "minimum": 0
          },
          "ape_ip90": {
            "type": [
              "number",
              "null"
            ],
            "description": "The catalog's APE at IP90: signed average percentage error from Novi's published report, as a fraction; can be negative. Null when the catalog doesn't report it."
          },
          "ape_ip1080": {
            "type": [
              "number",
              "null"
            ],
            "description": "The catalog's APE at IP1080: signed average percentage error from Novi's published report, as a fraction; can be negative. Null when the catalog doesn't report it."
          }
        },
        "additionalProperties": false
      },
      "ModelSetCatalog": {
        "type": "object",
        "description": "Curated from Novi's Intel basin report catalog (DS's published catalog of basin report models): the report, its dates and dataset, and its published oil and gas accuracy. Curated into the release file, not computed by this server.",
        "required": [
          "source",
          "report",
          "published",
          "vintage",
          "status",
          "dataset",
          "accuracy",
          "notes"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "The catalog source.",
            "minLength": 1
          },
          "report": {
            "type": "string",
            "description": "The basin report name, as the catalog lists it; an entry covers the set's own build.",
            "minLength": 1
          },
          "published": {
            "type": "string",
            "description": "The report publication date.",
            "format": "date"
          },
          "vintage": {
            "type": "string",
            "description": "The month of the set's build, YYYY-MM, as include=vintage gives it.",
            "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
          },
          "status": {
            "type": "string",
            "description": "The catalog entry publication status.",
            "enum": [
              "published"
            ]
          },
          "dataset": {
            "type": [
              "string",
              "null"
            ],
            "description": "The dataset named by the catalog, or null when it does not name one.",
            "minLength": 1
          },
          "accuracy": {
            "type": "object",
            "description": "Published oil and gas accuracy when reported.",
            "required": [],
            "properties": {
              "oil": {
                "$ref": "#/components/schemas/StreamAccuracy"
              },
              "gas": {
                "$ref": "#/components/schemas/StreamAccuracy"
              }
            },
            "additionalProperties": false
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "description": "Curator notes, or null when there are none.",
            "minLength": 1
          }
        },
        "additionalProperties": false
      },
      "ModelSetFrame": {
        "type": "object",
        "description": "The units a model set's own data and models are in. The API answers each quantity it names in the API's units whatever the set's: ft (structure-depth and thickness grids included), bbl/ft, lb/ft, bbl and mcf.\n\nGrid inputs it names no unit for, such as HCPV and pressure, answer in the set's own units. Drawn wells go to the set's models in its units and come back converted, by exact factors (1 ft = 0.3048 m, 1 bbl = 42 gal = 0.158987294928 m3, 1 mcf = 28.316846592 m3, 1 lb = 0.45359237 kg). Units only: not where depths are measured from.",
        "required": [
          "length",
          "fluid_per_length",
          "proppant_per_length",
          "production",
          "grid_length"
        ],
        "properties": {
          "length": {
            "type": "string",
            "description": "Lateral length, TVD and spacing distances in the set's data and models; the API answers in ft.",
            "enum": [
              "ft",
              "m"
            ]
          },
          "fluid_per_length": {
            "type": "string",
            "description": "Completion fluid per lateral length; the API answers in bbl/ft, and total fluid in bbl (the set's in bbl, gal or m3 to match).",
            "enum": [
              "bbl/ft",
              "gal/ft",
              "m3/m"
            ]
          },
          "proppant_per_length": {
            "type": "string",
            "description": "Proppant per lateral length; the API answers in lb/ft, and total proppant in lb (the set's in lb, kg or t to match).",
            "enum": [
              "lb/ft",
              "kg/m",
              "t/m"
            ]
          },
          "production": {
            "type": "object",
            "description": "Production volumes in the set's data and its models' targets.",
            "required": [
              "oil",
              "gas",
              "water"
            ],
            "properties": {
              "oil": {
                "type": "string",
                "description": "Oil volumes, the oil model's target among them; the API answers in bbl.",
                "enum": [
                  "bbl",
                  "m3"
                ]
              },
              "gas": {
                "type": "string",
                "description": "Gas volumes (e3m3 is thousands of m3); the API answers in mcf.",
                "enum": [
                  "mcf",
                  "e3m3"
                ]
              },
              "water": {
                "type": "string",
                "description": "Water volumes; the API answers in bbl.",
                "enum": [
                  "bbl",
                  "m3"
                ]
              }
            },
            "additionalProperties": false
          },
          "grid_length": {
            "type": "string",
            "description": "Structure-depth and thickness grid values; the API answers in ft.",
            "enum": [
              "ft",
              "m"
            ]
          }
        },
        "additionalProperties": false
      },
      "ModelSetSummary": {
        "type": "object",
        "description": "A model set.",
        "required": [
          "id",
          "label",
          "basin",
          "publisher",
          "default",
          "status",
          "error",
          "models",
          "streams",
          "stream_labels",
          "source"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The set's id, as `model_set` takes it.",
            "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
          },
          "label": {
            "type": "string",
            "description": "A name to show."
          },
          "basin": {
            "type": [
              "string",
              "null"
            ],
            "description": "The basin the set covers."
          },
          "publisher": {
            "type": [
              "string",
              "null"
            ],
            "description": "Who published the set; null for the default set."
          },
          "default": {
            "type": "boolean",
            "description": "True for the set that answers without `model_set`."
          },
          "status": {
            "type": "string",
            "description": "ready: loaded; loading: loading now; idle: loads on first use; unavailable: the last load failed (`error` says why; tried again after 60 s).",
            "enum": [
              "ready",
              "loading",
              "idle",
              "unavailable"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why the set is unavailable; null otherwise."
          },
          "models": {
            "type": "object",
            "description": "The model number per stream the set serves, as GET /models lists them under this set.",
            "required": [],
            "properties": {
              "oil": {
                "type": "string",
                "description": "Oil model number."
              },
              "gas": {
                "type": "string",
                "description": "Gas model number."
              },
              "water": {
                "type": "string",
                "description": "Water model number."
              }
            },
            "additionalProperties": false
          },
          "streams": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A stream.",
              "enum": [
                "oil",
                "gas",
                "water"
              ]
            },
            "description": "The streams the set serves, in oil, gas, water order.",
            "minItems": 1
          },
          "stream_labels": {
            "type": "object",
            "description": "A stream's label where it isn't the stream's name, as condensate in the oil slot; empty when every stream is its own name. On a set labelled `{\"oil\": \"condensate\"}` its oil forecasts, exports and model inputs are condensate, under the oil name, and so is its own wells' oil production when its dataset has `novi_condensate` and no `novi_oil`. Known without loading the set.",
            "required": [],
            "properties": {
              "oil": {
                "type": "string",
                "description": "What the oil slot holds.",
                "enum": [
                  "condensate"
                ]
              }
            },
            "additionalProperties": false
          },
          "source": {
            "type": [
              "object",
              "null"
            ],
            "description": "Where the set comes from, as the publisher names it (dataset, dataset_id, build_num and the like); null when unknown.",
            "additionalProperties": {
              "type": [
                "string",
                "number"
              ]
            }
          },
          "model_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "causal",
              "standard",
              null
            ],
            "description": "With include=model_type: causal for a causal, counterfactual model build (as Novi Causal Intel sets are), standard for a standard build, or null when the server doesn't say. The base dataset's (`id: default`) comes from the server's configuration, a published set's from its release file."
          },
          "facts": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ModelSetFacts"
              },
              {
                "type": "null"
              }
            ],
            "description": "With include=facts: figures about the set's data and models; null until the set has loaded once, or when its figures couldn't be computed (retried on a later request). A server restarted on the same disk answers with the figures it last computed for the same set build until the set loads."
          },
          "catalog": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ModelSetCatalog"
              },
              {
                "type": "null"
              }
            ],
            "description": "With include=catalog: the curated basin report catalog entry; null for the base dataset (`id: default`) and for sets the catalog has no entry for."
          },
          "frame": {
            "$ref": "#/components/schemas/ModelSetFrame",
            "description": "With include=frame: the units the set's own data and models are in. For reference only: every quantity it names is already in the API's units wherever this API answers it, so don't convert it; grid inputs it names no unit for, such as HCPV and pressure, are in the set's own units. The base dataset (`id: default`) and sets that declare no frame are in the API's units."
          },
          "vintage": {
            "type": [
              "string",
              "null"
            ],
            "description": "With include=vintage: the month of the Model Engine build the set's data and models come from, YYYY-MM, read from `source.build_num` (`B20260929-220731` is `2026-09`). Name a set by its basin and this month; it is the same kind of date for every set, and known before the set loads. Null when the source names no build.",
            "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
          },
          "subsurface_sampling": {
            "type": "string",
            "description": "With include=subsurface_sampling: where the set reads its subsurface grids at a well: `BOTTOM_HOLE`, `SURFACE_HOLE`, or `MIDPOINT` (both, averaged).\n\nIt applies to planned and drawn wells' model inputs, GET /subsurface/sample and GET /wells/{key}/subsurface. A set the release file marks to follow its subsurface config reads where its `grid_sampling_location` says (GET /subsurface `config.params`), as its training did; any other reads `MIDPOINT`. Left out until such a set has loaded (GET /model-sets/{model_set} loads it), and for a set without a subsurface model. Whatever it is, landings and TVD estimates use the formation top averaged over surface and bottom hole, and POST /gun-barrels its own sampling.",
            "enum": [
              "BOTTOM_HOLE",
              "SURFACE_HOLE",
              "MIDPOINT"
            ]
          },
          "formation_labels": {
            "type": "string",
            "description": "With include=formation_labels: `grid` for a set the server's release file marks as labelled from its own structure grids, with a depth pack: POST /tvd-estimates bounds a `structure_grid` estimate, and POST /gun-barrels and GET /wells/{key}/subsurface draw a header TVD outside its formation, a foot inside the nearer edge. Left out otherwise. Known without loading the set.",
            "enum": [
              "grid"
            ]
          },
          "pins": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ModelSetPins"
              },
              {
                "type": "null"
              }
            ],
            "description": "With include=pins (staff only): what the set is served from, as this server loaded it; null for the base dataset (`id: default`)."
          }
        },
        "additionalProperties": false
      },
      "ModelSetList": {
        "type": "object",
        "description": "The model sets.",
        "required": [
          "default",
          "model_sets"
        ],
        "properties": {
          "default": {
            "type": "string",
            "description": "The id of the set that answers without `model_set`: `default` (the base dataset), or the published set the server answers from instead."
          },
          "model_sets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ModelSetSummary"
            },
            "description": "Every model set: the one that answers without `model_set` first, then the others, `default` (unless the server retired it) before the release file's sets in its order."
          }
        },
        "additionalProperties": false
      },
      "ModelSetEntry": {
        "type": "object",
        "description": "A model set entry as a release file holds it, its optional keys checked as there.\n\n- Optional keys: `analogs`, `analog_shap` (its analogs' SHAP), `distribution`, `model_type`, `catalog`, `depth`, `frame`, `subsurface_sampling`, `pdp_extended`, `bands`, `formation_labels`, `stream_labels`, `versioned`.\n- `versioned: true`: the set's files sit at versioned paths in the sets store (each build's under its manifest, each sidecar under its sha256, its depth pin too), so a rebuild never overwrites files a served set reads.",
        "required": [
          "label",
          "basin",
          "publisher",
          "source",
          "models",
          "manifest_sha256"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The set's id, the path's; optional here.",
            "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
          },
          "label": {
            "type": "string",
            "description": "Its display name."
          },
          "basin": {
            "type": "string",
            "description": "The basin its wells are in."
          },
          "publisher": {
            "type": "string",
            "description": "Who built it."
          },
          "source": {
            "type": "object",
            "description": "Where its dataset came from: strings and numbers, such as `dataset_id` and `build_num`.",
            "additionalProperties": {
              "type": [
                "string",
                "number"
              ]
            }
          },
          "models": {
            "type": "object",
            "description": "Its forecast model per stream it serves: any of oil, gas and water, at least one; none is a 400.",
            "required": [],
            "properties": {
              "oil": {
                "type": "string",
                "description": "Model number."
              },
              "gas": {
                "type": "string",
                "description": "Model number."
              },
              "water": {
                "type": "string",
                "description": "Model number."
              }
            },
            "additionalProperties": false
          },
          "stream_labels": {
            "type": "object",
            "description": "`{\"oil\": \"condensate\"}` for a set whose oil model predicts condensate (`novi_condensate`). The set then answers it as `stream_labels`, its wells' oil production is their condensate, and its exports say so.\n\nAnything else is a 400, as is a label without an oil model; left out for any other set. The set loads only when the label and its oil model's target agree: a condensate model without the label, or the label on an oil model, leaves it `unavailable` with the reason.",
            "required": [
              "oil"
            ],
            "properties": {
              "oil": {
                "type": "string",
                "description": "What the oil slot holds.",
                "enum": [
                  "condensate"
                ]
              }
            },
            "additionalProperties": false
          },
          "manifest_sha256": {
            "type": "string",
            "description": "The sha256 of the set's manifest.json in the sets store.",
            "pattern": "^[0-9a-f]{64}$"
          },
          "fork": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "True for an id the server's release carries, so this environment serves this entry instead of the release's. It isn't stored with the entry."
          },
          "tenants": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^[a-z0-9]{1,63}$"
                },
                "uniqueItems": true
              },
              {
                "type": "null"
              }
            ],
            "description": "Staff only: the customer keys whose users may see and use this set, besides staff; null for every tenant. Only for an id the server's release doesn't carry, and required for a new one (a 400 without it); left out, a set the table already holds keeps its tenants. It isn't stored with the entry, and takes effect when `served_from` says."
          }
        },
        "additionalProperties": true
      },
      "ModelSetPins": {
        "type": "object",
        "description": "What a model set is served from.",
        "required": [
          "origin",
          "sha256",
          "pins",
          "release",
          "fork_of",
          "behind"
        ],
        "properties": {
          "origin": {
            "type": "string",
            "description": "`release`: the entry the server's release carries; `fork`: this environment's own entry for an id the release carries; `local`: this environment's own entry for an id it doesn't. A server that reads its table without a selection serves every row as stored, each a `fork` or `local`; one that reads only a release file serves `release` entries.",
            "enum": [
              "release",
              "fork",
              "local"
            ]
          },
          "sha256": {
            "type": "string",
            "description": "A digest of `pins`. A stored plan records the digest it started on, and resuming it under another fails it.",
            "pattern": "^[0-9a-f]{64}$"
          },
          "pins": {
            "type": "object",
            "additionalProperties": true,
            "description": "Each key of the entry that names its files or how they're read, when the entry has it: `manifest_sha256`, `versioned`, `models`, `frame`, `depth`, `analogs`, `analog_shap`, `distribution`, `pdp_extended`, `bands`, `subsurface_sampling`, `formation_labels`, `stream_labels`."
          },
          "release": {
            "anyOf": [
              {
                "type": "object",
                "description": "The release's entry for the id.",
                "required": [
                  "sha256",
                  "differs"
                ],
                "properties": {
                  "sha256": {
                    "type": "string",
                    "description": "The digest of the release entry's pins.",
                    "pattern": "^[0-9a-f]{64}$"
                  },
                  "differs": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Each pin the release gives otherwise, as the release gives it; null where the release has none."
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "A fork's: what the release this server runs carries for the id; null for `release` and `local`."
          },
          "fork_of": {
            "anyOf": [
              {
                "type": "object",
                "additionalProperties": true,
                "required": [
                  "sha256"
                ],
                "properties": {
                  "sha256": {
                    "type": "string",
                    "description": "The digest of those pins.",
                    "pattern": "^[0-9a-f]{64}$"
                  }
                },
                "description": "The release's pins, keyed as `pins` is."
              },
              {
                "type": "null"
              }
            ],
            "description": "A fork's: the release's pins when the fork was made; null for a fork from before forks were stamped, and for `release` and `local`."
          },
          "behind": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "A fork's: true when the release's pins moved since the fork was made; null without `fork_of`."
          }
        },
        "additionalProperties": false
      },
      "ModelSetPublished": {
        "type": "object",
        "description": "A published model set entry.",
        "required": [
          "model_set",
          "created",
          "served_from",
          "updated_by",
          "updated_at"
        ],
        "properties": {
          "model_set": {
            "type": "string",
            "description": "The set's id."
          },
          "created": {
            "type": "boolean",
            "description": "Whether the set was new."
          },
          "served_from": {
            "type": "string",
            "description": "When servers answer from it: a set new to a server from its next request, one it already serves after its next start.",
            "enum": [
              "next_request",
              "next_start"
            ]
          },
          "updated_by": {
            "type": "string",
            "description": "The publisher's email."
          },
          "updated_at": {
            "type": "string",
            "description": "When the table took the entry.",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "ModelSet": {
        "type": "object",
        "description": "A model set and its dataset.",
        "required": [
          "id",
          "label",
          "basin",
          "publisher",
          "default",
          "status",
          "error",
          "models",
          "streams",
          "stream_labels",
          "source",
          "dataset"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The set's id, as `model_set` takes it.",
            "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
          },
          "label": {
            "type": "string",
            "description": "A name to show."
          },
          "basin": {
            "type": [
              "string",
              "null"
            ],
            "description": "The basin the set covers."
          },
          "publisher": {
            "type": [
              "string",
              "null"
            ],
            "description": "Who published the set; null for the default set."
          },
          "default": {
            "type": "boolean",
            "description": "True for the set that answers without `model_set`."
          },
          "status": {
            "type": "string",
            "description": "ready: loaded; loading: loading now; idle: loads on first use; unavailable: the last load failed (`error` says why; tried again after 60 s).",
            "enum": [
              "ready",
              "loading",
              "idle",
              "unavailable"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why the set is unavailable; null otherwise."
          },
          "models": {
            "type": "object",
            "description": "The model number per stream the set serves, as GET /models lists them under this set.",
            "required": [],
            "properties": {
              "oil": {
                "type": "string",
                "description": "Oil model number."
              },
              "gas": {
                "type": "string",
                "description": "Gas model number."
              },
              "water": {
                "type": "string",
                "description": "Water model number."
              }
            },
            "additionalProperties": false
          },
          "streams": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A stream.",
              "enum": [
                "oil",
                "gas",
                "water"
              ]
            },
            "description": "The streams the set serves, in oil, gas, water order.",
            "minItems": 1
          },
          "stream_labels": {
            "type": "object",
            "description": "A stream's label where it isn't the stream's name, as condensate in the oil slot; empty when every stream is its own name. On a set labelled `{\"oil\": \"condensate\"}` its oil forecasts, exports and model inputs are condensate, under the oil name, and so is its own wells' oil production when its dataset has `novi_condensate` and no `novi_oil`. Known without loading the set.",
            "required": [],
            "properties": {
              "oil": {
                "type": "string",
                "description": "What the oil slot holds.",
                "enum": [
                  "condensate"
                ]
              }
            },
            "additionalProperties": false
          },
          "source": {
            "type": [
              "object",
              "null"
            ],
            "description": "Where the set comes from, as the publisher names it (dataset, dataset_id, build_num and the like); null when unknown.",
            "additionalProperties": {
              "type": [
                "string",
                "number"
              ]
            }
          },
          "model_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "causal",
              "standard",
              null
            ],
            "description": "With include=model_type: causal for a causal, counterfactual model build (as Novi Causal Intel sets are), standard for a standard build, or null when the server doesn't say. The base dataset's (`id: default`) comes from the server's configuration, a published set's from its release file."
          },
          "facts": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ModelSetFacts"
              },
              {
                "type": "null"
              }
            ],
            "description": "With include=facts: figures about the set's data and models; null until the set has loaded once, or when its figures couldn't be computed (retried on a later request). A server restarted on the same disk answers with the figures it last computed for the same set build until the set loads."
          },
          "catalog": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ModelSetCatalog"
              },
              {
                "type": "null"
              }
            ],
            "description": "With include=catalog: the curated basin report catalog entry; null for the base dataset (`id: default`) and for sets the catalog has no entry for."
          },
          "frame": {
            "$ref": "#/components/schemas/ModelSetFrame",
            "description": "With include=frame: the units the set's own data and models are in. For reference only: every quantity it names is already in the API's units wherever this API answers it, so don't convert it; grid inputs it names no unit for, such as HCPV and pressure, are in the set's own units. The base dataset (`id: default`) and sets that declare no frame are in the API's units."
          },
          "vintage": {
            "type": [
              "string",
              "null"
            ],
            "description": "With include=vintage: the month of the Model Engine build the set's data and models come from, YYYY-MM, read from `source.build_num` (`B20260929-220731` is `2026-09`). Name a set by its basin and this month; it is the same kind of date for every set, and known before the set loads. Null when the source names no build.",
            "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
          },
          "subsurface_sampling": {
            "type": "string",
            "description": "With include=subsurface_sampling: where the set reads its subsurface grids at a well: `BOTTOM_HOLE`, `SURFACE_HOLE`, or `MIDPOINT` (both, averaged).\n\nIt applies to planned and drawn wells' model inputs, GET /subsurface/sample and GET /wells/{key}/subsurface. A set the release file marks to follow its subsurface config reads where its `grid_sampling_location` says (GET /subsurface `config.params`), as its training did; any other reads `MIDPOINT`. Left out until such a set has loaded (GET /model-sets/{model_set} loads it), and for a set without a subsurface model. Whatever it is, landings and TVD estimates use the formation top averaged over surface and bottom hole, and POST /gun-barrels its own sampling.",
            "enum": [
              "BOTTOM_HOLE",
              "SURFACE_HOLE",
              "MIDPOINT"
            ]
          },
          "formation_labels": {
            "type": "string",
            "description": "With include=formation_labels: `grid` for a set the server's release file marks as labelled from its own structure grids, with a depth pack: POST /tvd-estimates bounds a `structure_grid` estimate, and POST /gun-barrels and GET /wells/{key}/subsurface draw a header TVD outside its formation, a foot inside the nearer edge. Left out otherwise. Known without loading the set.",
            "enum": [
              "grid"
            ]
          },
          "pins": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ModelSetPins"
              },
              {
                "type": "null"
              }
            ],
            "description": "With include=pins (staff only): what the set is served from, as this server loaded it; null for the base dataset (`id: default`)."
          },
          "dataset": {
            "type": "object",
            "description": "The set's dataset.",
            "required": [
              "well_count",
              "bbox",
              "as_of",
              "basin",
              "subbasin"
            ],
            "properties": {
              "well_count": {
                "type": "integer",
                "description": "Existing wells in the set."
              },
              "bbox": {
                "type": "array",
                "items": {
                  "type": "number",
                  "description": "Degrees."
                },
                "description": "Extent of the wells as [west, south, east, north].",
                "minItems": 4,
                "maxItems": 4
              },
              "as_of": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Latest production date.",
                "format": "date"
              },
              "basin": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Region, as the wells name it."
              },
              "subbasin": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Basin within the region, as the wells name it."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "Health": {
        "type": "object",
        "description": "Service health.",
        "required": [
          "status",
          "version",
          "sample_data",
          "dataset",
          "uptime_s",
          "host",
          "checks",
          "web"
        ],
        "properties": {
          "storage": {
            "type": "object",
            "description": "Only with a configured state store.",
            "required": [
              "kind",
              "tenant"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "description": "Adapter kind.",
                "enum": [
                  "s3",
                  "fs",
                  "memory"
                ]
              },
              "tenant": {
                "type": "string",
                "description": "Instance default tenant."
              }
            },
            "additionalProperties": false
          },
          "status": {
            "type": "string",
            "description": "ok when everything is ready, degraded otherwise.",
            "enum": [
              "ok",
              "degraded"
            ]
          },
          "version": {
            "type": "string",
            "description": "API version."
          },
          "sample_data": {
            "type": "boolean",
            "description": "True when the API serves synthetic sample data."
          },
          "dataset": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dataset name."
          },
          "uptime_s": {
            "type": "integer",
            "description": "Seconds since the server started."
          },
          "host": {
            "type": "object",
            "description": "The machine the server runs on.",
            "required": [
              "cpus",
              "cpu_model"
            ],
            "properties": {
              "cpus": {
                "type": "integer",
                "description": "CPUs the server can use."
              },
              "cpu_model": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "CPU model name, as the host reports it."
              }
            },
            "additionalProperties": false
          },
          "checks": {
            "type": "object",
            "description": "Component status.",
            "required": [
              "database",
              "subsurface",
              "spacing_and_features",
              "workers"
            ],
            "properties": {
              "database": {
                "type": "string",
                "description": "Well database.",
                "enum": [
                  "ok"
                ]
              },
              "subsurface": {
                "type": "string",
                "description": "Packed subsurface grids.",
                "enum": [
                  "ready",
                  "loading",
                  "unavailable"
                ]
              },
              "spacing_and_features": {
                "type": "string",
                "description": "Spacing and spacing feature tables for existing wells.",
                "enum": [
                  "ok",
                  "missing"
                ]
              },
              "workers": {
                "type": "object",
                "description": "Model workers.",
                "required": [
                  "spacing",
                  "calc",
                  "forecast"
                ],
                "properties": {
                  "spacing": {
                    "type": "string",
                    "description": "The spacing model worker.",
                    "enum": [
                      "ready",
                      "loading",
                      "down"
                    ]
                  },
                  "calc": {
                    "type": "string",
                    "description": "The calc model worker.",
                    "enum": [
                      "ready",
                      "loading",
                      "down"
                    ]
                  },
                  "forecast": {
                    "type": "string",
                    "description": "The forecast model worker.",
                    "enum": [
                      "ready",
                      "loading",
                      "down"
                    ]
                  }
                },
                "additionalProperties": false
              },
              "default_model_set": {
                "type": "object",
                "description": "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.",
                "required": [
                  "id",
                  "status",
                  "error"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The configured default set id."
                  },
                  "status": {
                    "type": "string",
                    "description": "The set's load state.",
                    "enum": [
                      "ready",
                      "loading",
                      "idle",
                      "unavailable"
                    ]
                  },
                  "error": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Why the set is unavailable; null otherwise."
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "app_version": {
            "type": "string",
            "description": "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."
          },
          "clients": {
            "type": "object",
            "description": "What each client of this API should run. Absent, with app_version, when the server can't read its VERSION.",
            "required": [
              "mcpb",
              "skill"
            ],
            "properties": {
              "mcpb": {
                "type": "object",
                "description": "The Claude Desktop extension (.mcpb).",
                "required": [
                  "version",
                  "min_supported",
                  "download",
                  "setup"
                ],
                "properties": {
                  "version": {
                    "type": "string",
                    "description": "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_supported": {
                    "type": "string",
                    "description": "The oldest extension still supported (semver). Older ones may fail to load some tools: tell the user to update before going on."
                  },
                  "download": {
                    "type": "string",
                    "description": "Path of this build's extension file on this origin, under the server's base path, when it has one."
                  },
                  "setup": {
                    "type": "string",
                    "description": "Path on this origin of the API page, whose \"Use it in Claude\" section explains setup and links the download."
                  }
                },
                "additionalProperties": false
              },
              "skill": {
                "type": "object",
                "description": "The Claude skill.",
                "required": [
                  "version",
                  "download"
                ],
                "properties": {
                  "version": {
                    "type": "string",
                    "description": "The build the skill zip comes from (VERSION, MAJOR.NN), as `app_version`: label the download with it."
                  },
                  "download": {
                    "type": "string",
                    "description": "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."
                  }
                },
                "additionalProperties": false
              },
              "mcp": {
                "type": "object",
                "description": "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`.",
                "required": [
                  "path"
                ],
                "properties": {
                  "path": {
                    "type": "string",
                    "description": "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."
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "web": {
            "type": "object",
            "description": "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`.",
            "required": [
              "status",
              "sha",
              "version",
              "requires_api",
              "checked_at",
              "error"
            ],
            "properties": {
              "status": {
                "type": "string",
                "description": "Whether the server serves its web channel's newest release.\n\n- `ok`: it does.\n- `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.\n- `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.\n- `disabled`: no web channel; the server serves its image's UI.",
                "enum": [
                  "ok",
                  "held",
                  "unavailable",
                  "disabled"
                ]
              },
              "sha": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Commit of the web UI release served (40 lowercase hex); null while the server serves the UI built into its image.",
                "pattern": "^[0-9a-f]{40}$"
              },
              "version": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Version of the web UI release served, as 1.0; null when `sha` is."
              },
              "requires_api": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Oldest API version (MAJOR.MINOR.PATCH) the release served needs; null when `sha` is."
              },
              "checked_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "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`.",
                "format": "date-time"
              },
              "error": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "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."
              },
              "newest": {
                "type": "object",
                "description": "The channel's newest release, sent only when it isn't the one served.",
                "required": [
                  "sha",
                  "version",
                  "requires_api"
                ],
                "properties": {
                  "sha": {
                    "type": "string",
                    "description": "Its commit (40 lowercase hex).",
                    "pattern": "^[0-9a-f]{40}$"
                  },
                  "version": {
                    "type": "string",
                    "description": "Its web UI version."
                  },
                  "requires_api": {
                    "type": "string",
                    "description": "Oldest API version it needs; above this server's `version` when status is `held`."
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "fe": {
            "type": "object",
            "description": "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`.",
            "required": [
              "pending",
              "failed",
              "scanned_at"
            ],
            "properties": {
              "pending": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Legacy Forecasts not yet read."
              },
              "failed": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Legacy Forecasts whose last read failed."
              },
              "scanned_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "When the last complete scan ended (ISO 8601, UTC).",
                "format": "date-time"
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "Dataset": {
        "type": "object",
        "description": "The dataset.",
        "required": [
          "name",
          "build",
          "sample_data",
          "basin",
          "region",
          "well_count",
          "formation_count",
          "as_of",
          "first_production",
          "bbox",
          "models",
          "ip_days",
          "spacing",
          "subsurface",
          "limits",
          "eur",
          "bands",
          "depletion_chain"
        ],
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dataset name."
          },
          "build": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dataset build."
          },
          "sample_data": {
            "type": "boolean",
            "description": "True when the data is synthetic."
          },
          "basin": {
            "type": [
              "string",
              "null"
            ],
            "description": "Basin, as Midland."
          },
          "region": {
            "type": [
              "string",
              "null"
            ],
            "description": "Region, as Permian."
          },
          "well_count": {
            "type": "integer",
            "description": "Wells in the dataset."
          },
          "formation_count": {
            "type": "integer",
            "description": "Formations with wells or grids."
          },
          "as_of": {
            "type": [
              "string",
              "null"
            ],
            "description": "Latest production date.",
            "format": "date"
          },
          "first_production": {
            "type": [
              "string",
              "null"
            ],
            "description": "Earliest first production.",
            "format": "date"
          },
          "bbox": {
            "type": "array",
            "items": {
              "type": "number",
              "description": "Degrees."
            },
            "description": "Extent of the wells: west, south, east, north.",
            "minItems": 4,
            "maxItems": 4
          },
          "models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ForecastModel"
            },
            "description": "Forecast model per stream."
          },
          "ip_days": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "Days since first production."
            },
            "description": "ip_days forecasts are reported at."
          },
          "spacing": {
            "type": "object",
            "description": "Spacing config.",
            "required": [
              "search_radius_ft"
            ],
            "properties": {
              "search_radius_ft": {
                "type": "number",
                "description": "Radius the spacing step searches for neighbors, ft."
              }
            },
            "additionalProperties": false
          },
          "subsurface": {
            "type": [
              "object",
              "null"
            ],
            "description": "Subsurface config.",
            "required": [
              "method",
              "grids",
              "distance_from_grids",
              "distance_from_grids_units"
            ],
            "properties": {
              "method": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Interpolation method."
              },
              "grids": {
                "type": "integer",
                "description": "Grids."
              },
              "distance_from_grids": {
                "type": "number",
                "description": "A point the set reads (its `subsurface_sampling` in GET /model-sets) farther than this from a grid is left out of that grid's value."
              },
              "distance_from_grids_units": {
                "type": "string",
                "description": "Units of distance_from_grids."
              }
            },
            "additionalProperties": false
          },
          "limits": {
            "type": "object",
            "description": "Request limits.",
            "required": [
              "forecast_wells",
              "plan_wells",
              "plan_unfinished_forecasts"
            ],
            "properties": {
              "forecast_wells": {
                "type": "integer",
                "description": "Most wells per POST /forecasts."
              },
              "plan_wells": {
                "type": "integer",
                "description": "Most forecasts (wells × designs) per POST /plans: the most wells with one design."
              },
              "plan_unfinished_forecasts": {
                "type": "integer",
                "description": "Most forecasts (wells × designs) one caller may have in queued or running plans once one is unfinished; POST /plans answers 429 past it."
              }
            },
            "additionalProperties": false
          },
          "eur": {
            "$ref": "#/components/schemas/DatasetEur"
          },
          "bands": {
            "$ref": "#/components/schemas/DatasetBands"
          },
          "depletion_chain": {
            "$ref": "#/components/schemas/DatasetDepletionChain"
          },
          "primary_stream": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "oil",
              "gas",
              null
            ],
            "description": "With include=primary_stream: oil or gas, whichever has the larger share of this model set's first-12-month BOE, summed over every well with a 12-month oil or gas volume, a missing stream counting as 0; null when the dataset has none at all; ties oil. Oil bbl is compared with gas mcf / 6 (GET /conventions boe); water is never primary."
          },
          "unlocated_well_count": {
            "type": "integer",
            "minimum": 0,
            "description": "With include=unlocated_well_count: how many of `well_count` wells have no location (no longitude). GET /wells lists only wells with a location, so it leaves these out, and no map or spatial filter places them. 0 when every well has one."
          }
        },
        "additionalProperties": false
      },
      "ForecastModel": {
        "type": "object",
        "description": "A forecast model.",
        "required": [
          "stream",
          "model_num",
          "target",
          "features",
          "ip_days"
        ],
        "properties": {
          "stream": {
            "type": "string",
            "description": "Stream.",
            "enum": [
              "oil",
              "gas",
              "water"
            ]
          },
          "model_num": {
            "type": "string",
            "description": "Model number."
          },
          "target": {
            "type": "string",
            "description": "Target column."
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Feature column."
            },
            "description": "Model input features."
          },
          "ip_days": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "Day."
            },
            "description": "ip_days the model predicts."
          }
        },
        "additionalProperties": false
      },
      "FormationList": {
        "type": "object",
        "description": "Formations.",
        "required": [
          "formations"
        ],
        "properties": {
          "formations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Formation"
            },
            "description": "Formations, top to bottom."
          }
        },
        "additionalProperties": false
      },
      "Formation": {
        "type": "object",
        "description": "A formation.",
        "required": [
          "name",
          "label",
          "well_count",
          "median_tvd_ft",
          "median_lateral_ft",
          "grids",
          "has_grids"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Name as stored and as inputs take it."
          },
          "label": {
            "type": "string",
            "description": "Display name."
          },
          "well_count": {
            "type": "integer",
            "description": "Wells landed in it."
          },
          "median_tvd_ft": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Median TVD of its wells, ft."
          },
          "median_lateral_ft": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Median lateral length of its wells, ft."
          },
          "grids": {
            "type": "object",
            "description": "Grid feature name per rock property.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "has_grids": {
            "type": "boolean",
            "description": "Whether it has subsurface grids."
          },
          "target": {
            "type": "boolean",
            "description": "With include=target: true for a formation the models were trained in that has wells and grids. Use it for planning and well pickers; keep every formation in legends, filters and existing-well displays.\n\nPrecisely: well_count above 0, has_grids true, and a novi_formation level (GET /models inputs) of every served model that lists those levels; wells and grids alone when none does. A forecast in a formation the models weren't trained in comes back with checks.unknown_formation."
          }
        },
        "additionalProperties": false
      },
      "Changelog": {
        "type": "object",
        "description": "What changed, release by release.",
        "required": [
          "version",
          "api_version",
          "unreleased",
          "releases",
          "next_cursor"
        ],
        "properties": {
          "version": {
            "type": "string",
            "description": "This build's version (VERSION, MAJOR.NN), as 0.15: the newest release."
          },
          "api_version": {
            "type": "string",
            "description": "API version, as GET /health reports it."
          },
          "unreleased": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChangelogEntry"
            },
            "description": "Merged and deployed with this build but not released yet, in the order the next release will list them; the same on every page."
          },
          "releases": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChangelogRelease"
            },
            "description": "This page of releases (newer than since, when given), newest first."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Cursor for the next page, null on the last."
          }
        },
        "additionalProperties": false
      },
      "ChangelogRelease": {
        "type": "object",
        "description": "A release.",
        "required": [
          "version",
          "tag",
          "date",
          "entries"
        ],
        "properties": {
          "version": {
            "type": "string",
            "description": "Version, MAJOR.NN, as 0.15."
          },
          "tag": {
            "type": "string",
            "description": "Its git tag, as v0.15."
          },
          "date": {
            "type": "string",
            "description": "Release date (UTC).",
            "format": "date"
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChangelogEntry"
            },
            "description": "What the release changed, in changelog order.",
            "minItems": 1
          }
        },
        "additionalProperties": false
      },
      "ChangelogEntry": {
        "type": "object",
        "description": "One change.",
        "required": [
          "tag",
          "text",
          "prs"
        ],
        "properties": {
          "tag": {
            "type": "string",
            "description": "Kind of change.",
            "enum": [
              "New",
              "Change",
              "Fix",
              "Remove"
            ]
          },
          "text": {
            "type": "string",
            "description": "The entry as written, without its trailing pull request reference."
          },
          "prs": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "A pull request number."
            },
            "description": "Pull requests the entry names at its end, as (#19) or (#14, #15); empty when it names none."
          }
        },
        "additionalProperties": false
      },
      "WellColumns": {
        "type": "object",
        "description": "Wells as columns.",
        "required": [
          "format",
          "count",
          "columns"
        ],
        "properties": {
          "format": {
            "type": "string",
            "description": "Layout.",
            "const": "columns"
          },
          "count": {
            "type": "integer",
            "description": "Wells."
          },
          "columns": {
            "type": "object",
            "description": "Parallel arrays, one entry per well. With `fields`, only the asked properties are present.",
            "required": [
              "wellbore_key"
            ],
            "properties": {
              "wellbore_key": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "Key."
                },
                "description": "Wellbore keys."
              },
              "well_name": {
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Name."
                },
                "description": "Well names."
              },
              "operator": {
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Operator."
                },
                "description": "Current operators."
              },
              "formation": {
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Formation."
                },
                "description": "Formations."
              },
              "mid_lon": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Degrees."
                },
                "description": "Lateral midpoint longitude."
              },
              "mid_lat": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Degrees."
                },
                "description": "Lateral midpoint latitude."
              },
              "shl_lon": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Degrees."
                },
                "description": "Surface hole longitude."
              },
              "shl_lat": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Degrees."
                },
                "description": "Surface hole latitude."
              },
              "heel_lon": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Degrees."
                },
                "description": "Heel longitude (null when not reported)."
              },
              "heel_lat": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Degrees."
                },
                "description": "Heel latitude."
              },
              "bhl_lon": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Degrees."
                },
                "description": "Bottom hole longitude."
              },
              "bhl_lat": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Degrees."
                },
                "description": "Bottom hole latitude."
              },
              "cum_boe_12": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "BOE."
                },
                "description": "First 12 months of production, BOE (gas at 6 mcf per bbl)."
              },
              "first_year": {
                "type": "array",
                "items": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Year."
                },
                "description": "Year of first production."
              },
              "distance_mi": {
                "type": "array",
                "items": {
                  "type": "number",
                  "description": "Miles."
                },
                "description": "With near only: great-circle miles from near to the lateral midpoint, rounded to 0.01; the wells come nearest first."
              },
              "area_distance_ft": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "description": "Feet.",
                  "minimum": 0
                },
                "description": "POST /wells/search only: 0 inside the area or on its edge, else feet from it, rounded and at least 1."
              },
              "basin": {
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Basin. Only when named in fields."
                },
                "description": "Basin. Only when named in fields."
              },
              "subbasin": {
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Sub-basin. Only when named in fields."
                },
                "description": "Sub-basin. Only when named in fields."
              },
              "state": {
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "State. Only when named in fields."
                },
                "description": "State. Only when named in fields."
              },
              "county": {
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "County. Only when named in fields."
                },
                "description": "County. Only when named in fields."
              },
              "lateral_length": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Lateral length, ft. Only when named in fields."
                },
                "description": "Lateral length, ft. Only when named in fields."
              },
              "tvd_td": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "TVD, ft. Only when named in fields."
                },
                "description": "TVD, ft. Only when named in fields."
              },
              "lat": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "The header's latitude, the midpoint of the surface and bottom holes, to 5 decimals; the map uses mid_lat. Only when named in fields."
                },
                "description": "The header's latitude, the midpoint of the surface and bottom holes, to 5 decimals; the map uses mid_lat. Only when named in fields."
              },
              "lon": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "The header's longitude, the midpoint of the surface and bottom holes, to 5 decimals; the map uses mid_lon. Only when named in fields."
                },
                "description": "The header's longitude, the midpoint of the surface and bottom holes, to 5 decimals; the map uses mid_lon. Only when named in fields."
              },
              "first_prod": {
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "First production, YYYY-MM-DD. Only when named in fields.",
                  "format": "date"
                },
                "description": "First production, YYYY-MM-DD. Only when named in fields."
              },
              "last_prod": {
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Last production, YYYY-MM-DD. Only when named in fields.",
                  "format": "date"
                },
                "description": "Last production, YYYY-MM-DD. Only when named in fields."
              },
              "cum_oil_12": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "First 12 months oil, whole bbl. Only when named in fields."
                },
                "description": "First 12 months oil, whole bbl. Only when named in fields."
              },
              "cum_gas_12": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "First 12 months gas, whole mcf. Only when named in fields."
                },
                "description": "First 12 months gas, whole mcf. Only when named in fields."
              },
              "cum_oil_life": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Cumulative oil, whole bbl. Only when named in fields."
                },
                "description": "Cumulative oil, whole bbl. Only when named in fields."
              },
              "cum_gas_life": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Cumulative gas, whole mcf. Only when named in fields."
                },
                "description": "Cumulative gas, whole mcf. Only when named in fields."
              },
              "cum_boe_life": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Cumulative BOE, whole. Only when named in fields."
                },
                "description": "Cumulative BOE, whole. Only when named in fields."
              },
              "total_proppant": {
                "type": "array",
                "items": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Proppant, lb. Only when named in fields."
                },
                "description": "Proppant, lb. Only when named in fields."
              },
              "total_fluid": {
                "type": "array",
                "items": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Fluid, bbl. Only when named in fields."
                },
                "description": "Fluid, bbl. Only when named in fields."
              },
              "stage_count": {
                "type": "array",
                "items": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Frac stages. Only when named in fields."
                },
                "description": "Frac stages. Only when named in fields."
              },
              "frac_date": {
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Frac date, YYYY-MM-DD. Only when named in fields.",
                  "format": "date"
                },
                "description": "Frac date, YYYY-MM-DD. Only when named in fields."
              },
              "til_date": {
                "type": "array",
                "items": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Turn-in-line date, YYYY-MM-DD. Only when named in fields.",
                  "format": "date"
                },
                "description": "Turn-in-line date, YYYY-MM-DD. Only when named in fields."
              },
              "fluid_bbl_per_ft": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Completion fluid per lateral ft, bbl/ft to 0.1: the header's novi_calc_fluid_per_length, the per-well value GET /completions/defaults and POST /units/summary take medians of. Only when named in fields."
                },
                "description": "Completion fluid per lateral ft, bbl/ft to 0.1: the header's novi_calc_fluid_per_length, the per-well value GET /completions/defaults and POST /units/summary take medians of. Only when named in fields."
              },
              "proppant_lb_per_ft": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Proppant per lateral ft, lb/ft to 0.1: the header's novi_calc_proppant_per_length, as fluid_bbl_per_ft. Only when named in fields."
                },
                "description": "Proppant per lateral ft, lb/ft to 0.1: the header's novi_calc_proppant_per_length, as fluid_bbl_per_ft. Only when named in fields."
              },
              "cum_boe_12_per_1000_ft": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "First 12 months of BOE per 1,000 ft of lateral (cum_boe_12 / lateral_length × 1,000, as POST /units/summary computes it), whole BOE. Only when named in fields."
                },
                "description": "First 12 months of BOE per 1,000 ft of lateral (cum_boe_12 / lateral_length × 1,000, as POST /units/summary computes it), whole BOE. Only when named in fields."
              },
              "cum_oil_12_per_1000_ft": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "First 12 months of oil per 1,000 ft of lateral (cum_oil_12 / lateral_length × 1,000), whole bbl; null without a 12-month oil volume or a lateral. As cum_boe_12_per_1000_ft, for the oil or gas basis of a per-lateral comparison. Only when named in fields."
                },
                "description": "First 12 months of oil per 1,000 ft of lateral (cum_oil_12 / lateral_length × 1,000), whole bbl; null without a 12-month oil volume or a lateral. As cum_boe_12_per_1000_ft, for the oil or gas basis of a per-lateral comparison. Only when named in fields."
              },
              "cum_gas_12_per_1000_ft": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "First 12 months of gas per 1,000 ft of lateral (cum_gas_12 / lateral_length × 1,000), whole mcf; null without a 12-month gas volume or a lateral. As cum_boe_12_per_1000_ft, for the oil or gas basis of a per-lateral comparison. Only when named in fields."
                },
                "description": "First 12 months of gas per 1,000 ft of lateral (cum_gas_12 / lateral_length × 1,000), whole mcf; null without a 12-month gas volume or a lateral. As cum_boe_12_per_1000_ft, for the oil or gas basis of a per-lateral comparison. Only when named in fields."
              }
            },
            "additionalProperties": false
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "With limit or cursor: cursor for the next page, null on the last; count is still every matching well."
          },
          "applied": {
            "type": "object",
            "additionalProperties": {
              "anyOf": [
                {
                  "type": [
                    "number",
                    "string",
                    "boolean",
                    "null"
                  ]
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "description": "How the server read `sort`, `order`, `county`, `operators`, the `_min` and `_max` ranges and, when format=columns is paged, `limit` and `cursor`, as {\"lateral_length_min\": 9000, \"sort\": \"cum_boe_12\", \"order\": \"desc\"}. Absent when none of them was sent."
          }
        },
        "additionalProperties": false
      },
      "WellFeatureCollection": {
        "type": "object",
        "description": "A page of wells as GeoJSON.",
        "required": [
          "type",
          "count",
          "next_cursor",
          "features"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "GeoJSON type.",
            "const": "FeatureCollection"
          },
          "count": {
            "type": "integer",
            "description": "Wells matching the filters (all pages)."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Cursor for the next page, null on the last."
          },
          "features": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WellFeature"
            },
            "description": "This page of wells."
          },
          "applied": {
            "type": "object",
            "additionalProperties": {
              "anyOf": [
                {
                  "type": [
                    "number",
                    "string",
                    "boolean",
                    "null"
                  ]
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "description": "How the server read `sort`, `order`, `county`, `operators`, the `_min` and `_max` ranges and, when format=columns is paged, `limit` and `cursor`, as {\"lateral_length_min\": 9000, \"sort\": \"cum_boe_12\", \"order\": \"desc\"}. Absent when none of them was sent."
          }
        },
        "additionalProperties": false
      },
      "WellFeature": {
        "type": "object",
        "description": "A well.",
        "required": [
          "type",
          "id",
          "geometry",
          "properties"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "GeoJSON type.",
            "const": "Feature"
          },
          "id": {
            "type": "string",
            "description": "Wellbore key."
          },
          "geometry": {
            "type": "object",
            "description": "Lateral midpoint.",
            "required": [
              "type",
              "coordinates"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "Geometry type.",
                "const": "Point"
              },
              "coordinates": {
                "type": "array",
                "description": "Lateral midpoint.",
                "prefixItems": [
                  {
                    "type": "number",
                    "description": "Longitude",
                    "minimum": -180,
                    "maximum": 180
                  },
                  {
                    "type": "number",
                    "description": "Latitude",
                    "minimum": -90,
                    "maximum": 90
                  }
                ],
                "minItems": 2,
                "maxItems": 2,
                "items": false
              }
            },
            "additionalProperties": false
          },
          "properties": {
            "type": "object",
            "description": "Well attributes. With `fields`, only the asked properties are present.",
            "required": [
              "wellbore_key"
            ],
            "properties": {
              "wellbore_key": {
                "type": "string",
                "description": "Key."
              },
              "well_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Name."
              },
              "operator": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Operator."
              },
              "formation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Formation."
              },
              "first_prod": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "First production.",
                "format": "date"
              },
              "lateral_length": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Lateral length, ft."
              },
              "tvd_td": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "TVD, ft."
              },
              "cum_boe_12": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "First 12 months, BOE."
              },
              "shl_lon": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Surface hole longitude."
              },
              "shl_lat": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Surface hole latitude."
              },
              "heel_lon": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Heel longitude."
              },
              "heel_lat": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Heel latitude."
              },
              "bhl_lon": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Bottom hole longitude."
              },
              "bhl_lat": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Bottom hole latitude."
              },
              "distance_mi": {
                "type": "number",
                "description": "With near only: great-circle miles from near to the lateral midpoint, rounded to 0.01."
              },
              "area_distance_ft": {
                "type": "integer",
                "description": "POST /wells/search only: 0 inside the area or on its edge, else feet from it, rounded and at least 1.",
                "minimum": 0
              },
              "basin": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Basin. Only when named in fields."
              },
              "subbasin": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Sub-basin. Only when named in fields."
              },
              "state": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "State. Only when named in fields."
              },
              "county": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "County. Only when named in fields."
              },
              "lat": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The header's latitude, the midpoint of the surface and bottom holes, to 5 decimals; the map uses mid_lat. Only when named in fields."
              },
              "lon": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The header's longitude, the midpoint of the surface and bottom holes, to 5 decimals; the map uses mid_lon. Only when named in fields."
              },
              "last_prod": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Last production, YYYY-MM-DD. Only when named in fields.",
                "format": "date"
              },
              "cum_oil_12": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "First 12 months oil, whole bbl. Only when named in fields."
              },
              "cum_gas_12": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "First 12 months gas, whole mcf. Only when named in fields."
              },
              "cum_oil_life": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Cumulative oil, whole bbl. Only when named in fields."
              },
              "cum_gas_life": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Cumulative gas, whole mcf. Only when named in fields."
              },
              "cum_boe_life": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Cumulative BOE, whole. Only when named in fields."
              },
              "total_proppant": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Proppant, lb. Only when named in fields."
              },
              "total_fluid": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Fluid, bbl. Only when named in fields."
              },
              "stage_count": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Frac stages. Only when named in fields."
              },
              "frac_date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Frac date, YYYY-MM-DD. Only when named in fields.",
                "format": "date"
              },
              "til_date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Turn-in-line date, YYYY-MM-DD. Only when named in fields.",
                "format": "date"
              },
              "first_year": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Year of first production. Only when named in fields."
              },
              "fluid_bbl_per_ft": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Completion fluid per lateral ft, bbl/ft to 0.1: the header's novi_calc_fluid_per_length, the per-well value GET /completions/defaults and POST /units/summary take medians of. Only when named in fields."
              },
              "proppant_lb_per_ft": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Proppant per lateral ft, lb/ft to 0.1: the header's novi_calc_proppant_per_length, as fluid_bbl_per_ft. Only when named in fields."
              },
              "cum_boe_12_per_1000_ft": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "First 12 months of BOE per 1,000 ft of lateral (cum_boe_12 / lateral_length × 1,000, as POST /units/summary computes it), whole BOE. Only when named in fields."
              },
              "cum_oil_12_per_1000_ft": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "First 12 months of oil per 1,000 ft of lateral (cum_oil_12 / lateral_length × 1,000), whole bbl; null without a 12-month oil volume or a lateral. As cum_boe_12_per_1000_ft, for the oil or gas basis of a per-lateral comparison. Only when named in fields."
              },
              "cum_gas_12_per_1000_ft": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "First 12 months of gas per 1,000 ft of lateral (cum_gas_12 / lateral_length × 1,000), whole mcf; null without a 12-month gas volume or a lateral. As cum_boe_12_per_1000_ft, for the oil or gas basis of a per-lateral comparison. Only when named in fields."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "Well": {
        "type": "object",
        "description": "A well. With `fields`, only the asked properties are present.",
        "required": [
          "wellbore_key"
        ],
        "properties": {
          "wellbore_key": {
            "type": "string",
            "description": "Wellbore key."
          },
          "well_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Well name."
          },
          "operator": {
            "type": [
              "string",
              "null"
            ],
            "description": "Current operator."
          },
          "basin": {
            "type": [
              "string",
              "null"
            ],
            "description": "Basin."
          },
          "subbasin": {
            "type": [
              "string",
              "null"
            ],
            "description": "Sub-basin."
          },
          "state": {
            "type": [
              "string",
              "null"
            ],
            "description": "State."
          },
          "county": {
            "type": [
              "string",
              "null"
            ],
            "description": "County."
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Landing formation."
          },
          "lateral_length": {
            "type": [
              "number",
              "null"
            ],
            "description": "Lateral length, ft."
          },
          "tvd_td": {
            "type": [
              "number",
              "null"
            ],
            "description": "True vertical depth, ft."
          },
          "shl_lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Surface hole latitude."
          },
          "shl_lon": {
            "type": [
              "number",
              "null"
            ],
            "description": "Surface hole longitude."
          },
          "bhl_lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Bottom hole latitude."
          },
          "bhl_lon": {
            "type": [
              "number",
              "null"
            ],
            "description": "Bottom hole longitude."
          },
          "heel_lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Heel latitude."
          },
          "heel_lon": {
            "type": [
              "number",
              "null"
            ],
            "description": "Heel longitude."
          },
          "lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Header latitude."
          },
          "lon": {
            "type": [
              "number",
              "null"
            ],
            "description": "Header longitude."
          },
          "first_prod": {
            "type": [
              "string",
              "null"
            ],
            "description": "First production.",
            "format": "date"
          },
          "last_prod": {
            "type": [
              "string",
              "null"
            ],
            "description": "Last production.",
            "format": "date"
          },
          "cum_oil_12": {
            "type": [
              "number",
              "null"
            ],
            "description": "First 12 months oil, whole bbl."
          },
          "cum_gas_12": {
            "type": [
              "number",
              "null"
            ],
            "description": "First 12 months gas, whole mcf."
          },
          "cum_boe_12": {
            "type": [
              "number",
              "null"
            ],
            "description": "First 12 months, whole BOE."
          },
          "cum_oil_life": {
            "type": [
              "number",
              "null"
            ],
            "description": "Cumulative oil, whole bbl."
          },
          "cum_gas_life": {
            "type": [
              "number",
              "null"
            ],
            "description": "Cumulative gas, whole mcf."
          },
          "cum_boe_life": {
            "type": [
              "number",
              "null"
            ],
            "description": "Cumulative BOE, whole."
          },
          "total_proppant": {
            "type": [
              "number",
              "null"
            ],
            "description": "Proppant, whole lb."
          },
          "total_fluid": {
            "type": [
              "number",
              "null"
            ],
            "description": "Fluid, whole bbl."
          },
          "stage_count": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Frac stages."
          },
          "frac_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "Frac date.",
            "format": "date"
          },
          "til_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "Turn-in-line date.",
            "format": "date"
          },
          "floored": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A field name.",
              "enum": [
                "first_prod",
                "cum_oil_12",
                "cum_gas_12",
                "cum_boe_12",
                "cum_oil_life",
                "cum_gas_life",
                "cum_boe_life"
              ]
            },
            "description": "With include=floors only: the fields here whose value may start at the dataset's first production month rather than at the well's own start (`first_prod` is then that floor month; 12-month and to-date volumes count only from it). Empty for a well that isn't floored."
          }
        },
        "additionalProperties": false
      },
      "Production": {
        "type": "object",
        "description": "Production history.",
        "required": [
          "wellbore_key",
          "count",
          "units",
          "rows"
        ],
        "properties": {
          "wellbore_key": {
            "type": "string",
            "description": "Wellbore key."
          },
          "count": {
            "type": "integer",
            "description": "Rows."
          },
          "units": {
            "type": "object",
            "description": "Units per column.",
            "required": [
              "oil",
              "gas",
              "water",
              "cum_oil",
              "cum_gas",
              "cum_water"
            ],
            "properties": {
              "oil": {
                "type": "string",
                "description": "Unit of oil."
              },
              "gas": {
                "type": "string",
                "description": "Unit of gas."
              },
              "water": {
                "type": "string",
                "description": "Unit of water."
              },
              "cum_oil": {
                "type": "string",
                "description": "Unit of cum_oil."
              },
              "cum_gas": {
                "type": "string",
                "description": "Unit of cum_gas."
              },
              "cum_water": {
                "type": "string",
                "description": "Unit of cum_water."
              }
            },
            "additionalProperties": false
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A period.",
              "required": [
                "date",
                "ip_day",
                "oil",
                "gas",
                "water",
                "cum_oil",
                "cum_gas",
                "cum_water"
              ],
              "properties": {
                "date": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Production date, the end of the period.",
                  "format": "date"
                },
                "ip_day": {
                  "type": "integer",
                  "description": "Days since first production."
                },
                "oil": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Oil rate, bbl/d."
                },
                "gas": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Gas rate, mcf/d."
                },
                "water": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Water rate, bbl/d."
                },
                "cum_oil": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Cumulative oil, bbl."
                },
                "cum_gas": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Cumulative gas, mcf."
                },
                "cum_water": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Cumulative water, bbl."
                }
              },
              "additionalProperties": false
            },
            "description": "Periods by ip_day."
          }
        },
        "additionalProperties": false
      },
      "SpacingNeighbor": {
        "type": "object",
        "description": "A spacing neighbor: the spacing step's edge, the neighbor's location and, for drawn wells, its impact feature columns.",
        "required": [
          "neighbor",
          "position"
        ],
        "properties": {
          "neighbor": {
            "type": "string",
            "description": "Neighbor wellbore key, or DRAWN-<index> for another drawn well."
          },
          "well_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Neighbor name."
          },
          "operator": {
            "type": [
              "string",
              "null"
            ],
            "description": "Neighbor operator."
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Neighbor formation."
          },
          "first_prod": {
            "type": [
              "string",
              "null"
            ],
            "description": "Neighbor first production.",
            "format": "date"
          },
          "heel_lon": {
            "type": [
              "number",
              "null"
            ],
            "description": "Neighbor heel longitude."
          },
          "heel_lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Neighbor heel latitude."
          },
          "bhl_lon": {
            "type": [
              "number",
              "null"
            ],
            "description": "Neighbor bottom hole longitude."
          },
          "bhl_lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Neighbor bottom hole latitude."
          },
          "position": {
            "type": "string",
            "description": "lateral, stack or stagger."
          },
          "cone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Cone, as leftstaggerbelow."
          },
          "category": {
            "type": [
              "string",
              "null"
            ],
            "description": "parent or nonparent."
          },
          "signedxy": {
            "type": [
              "number",
              "null"
            ],
            "description": "Horizontal offset, ft (+ right looking heel to toe)."
          },
          "signedtvd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Vertical offset, ft (+ deeper)."
          },
          "minxy": {
            "type": [
              "number",
              "null"
            ],
            "description": "Minimum horizontal distance, ft."
          },
          "mintvd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Minimum vertical distance, ft."
          },
          "mintangent": {
            "type": [
              "number",
              "null"
            ],
            "description": "Minimum 3D distance, ft."
          },
          "overlap": {
            "type": [
              "number",
              "null"
            ],
            "description": "Fraction of the lateral the neighbor overlaps."
          },
          "edge_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "Date the edge applies from.",
            "format": "date"
          }
        },
        "additionalProperties": {
          "type": [
            "number",
            "string",
            "boolean",
            "null"
          ]
        }
      },
      "WellSpacing": {
        "type": "object",
        "description": "Spacing.",
        "required": [
          "wellbore_key",
          "node",
          "neighbors"
        ],
        "properties": {
          "wellbore_key": {
            "type": "string",
            "description": "Wellbore key."
          },
          "node": {
            "type": [
              "object",
              "null"
            ],
            "description": "The well's spacing node, or null.",
            "required": [
              "wellbore_key",
              "azimuth",
              "heel_is_virtual",
              "heel_lon",
              "heel_lat",
              "pad_id",
              "pad_wells"
            ],
            "properties": {
              "wellbore_key": {
                "type": "string",
                "description": "Wellbore key."
              },
              "azimuth": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Lateral azimuth, degrees."
              },
              "heel_is_virtual": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "Heel estimated from the pad."
              },
              "heel_lon": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Heel longitude."
              },
              "heel_lat": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Heel latitude."
              },
              "pad_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Pad id."
              },
              "pad_wells": {
                "type": "integer",
                "description": "Wells on the pad."
              }
            },
            "additionalProperties": false
          },
          "neighbors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpacingNeighbor"
            },
            "description": "Neighbors, closest (mintangent) first."
          }
        },
        "additionalProperties": false
      },
      "FeatureValues": {
        "type": "object",
        "description": "Spacing feature columns by name.",
        "additionalProperties": {
          "type": [
            "number",
            "string",
            "boolean",
            "null"
          ]
        }
      },
      "WellFeatures": {
        "type": "object",
        "description": "Spacing features.",
        "required": [
          "wellbore_key",
          "ip_day",
          "features",
          "neighbors"
        ],
        "properties": {
          "wellbore_key": {
            "type": "string",
            "description": "Wellbore key."
          },
          "ip_day": {
            "type": [
              "integer",
              "null"
            ],
            "description": "ip_day of the features."
          },
          "features": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FeatureValues"
              },
              {
                "type": "null"
              }
            ],
            "description": "Node features, or null when not computed."
          },
          "neighbors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "neighbor"
              ],
              "properties": {
                "neighbor": {
                  "type": "string",
                  "description": "Neighbor wellbore key."
                }
              },
              "additionalProperties": {
                "type": [
                  "number",
                  "string",
                  "boolean",
                  "null"
                ]
              },
              "description": "Neighbor impact columns."
            },
            "description": "Per-neighbor features."
          }
        },
        "additionalProperties": false
      },
      "SubsurfaceModel": {
        "type": "object",
        "description": "Subsurface model.",
        "required": [
          "dataset",
          "config",
          "formations",
          "properties",
          "grids"
        ],
        "properties": {
          "dataset": {
            "type": "object",
            "description": "Subsurface dataset.",
            "required": [
              "id",
              "name",
              "build_num"
            ],
            "properties": {
              "id": {
                "type": "integer",
                "description": "Id."
              },
              "name": {
                "type": "string",
                "description": "Name."
              },
              "build_num": {
                "type": "string",
                "description": "Build."
              }
            },
            "additionalProperties": false
          },
          "config": {
            "type": "object",
            "description": "Interpolation config: method, projection and params.distance_from_grids.",
            "additionalProperties": true
          },
          "formations": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Formation."
            },
            "description": "Formations with grids."
          },
          "properties": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Rock property."
            },
            "description": "Rock properties."
          },
          "grids": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A grid.",
              "required": [
                "feature_name",
                "formation",
                "rock_property",
                "unit"
              ],
              "properties": {
                "feature_name": {
                  "type": "string",
                  "description": "Grid name."
                },
                "formation": {
                  "type": "string",
                  "description": "Formation."
                },
                "rock_property": {
                  "type": "string",
                  "description": "Property."
                },
                "unit": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "ft or fraction."
                }
              },
              "additionalProperties": false
            },
            "description": "Grids."
          }
        },
        "additionalProperties": false
      },
      "SubsurfaceGrid": {
        "type": "object",
        "description": "Grid points.",
        "required": [
          "feature_name",
          "formation",
          "rock_property",
          "unit",
          "count",
          "range",
          "lattice",
          "lng",
          "lat",
          "val"
        ],
        "properties": {
          "feature_name": {
            "type": "string",
            "description": "Grid name."
          },
          "formation": {
            "type": "string",
            "description": "Formation."
          },
          "rock_property": {
            "type": "string",
            "description": "Property."
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "ft or fraction."
          },
          "count": {
            "type": "integer",
            "description": "Points."
          },
          "range": {
            "type": "object",
            "description": "Value range.",
            "required": [
              "min",
              "p02",
              "p98",
              "max"
            ],
            "properties": {
              "min": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Minimum."
              },
              "p02": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "2nd percentile."
              },
              "p98": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "98th percentile."
              },
              "max": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Maximum."
              }
            },
            "additionalProperties": false
          },
          "lattice": {
            "type": [
              "object",
              "null"
            ],
            "description": "The regular lattice under the points, or null.",
            "required": [
              "lng0",
              "lat0",
              "step_lng",
              "step_lat",
              "nx",
              "ny"
            ],
            "properties": {
              "lng0": {
                "type": "number",
                "description": "Westmost column longitude."
              },
              "lat0": {
                "type": "number",
                "description": "Southmost row latitude."
              },
              "step_lng": {
                "type": "number",
                "description": "Column step, degrees."
              },
              "step_lat": {
                "type": "number",
                "description": "Row step, degrees."
              },
              "nx": {
                "type": "integer",
                "description": "Columns."
              },
              "ny": {
                "type": "integer",
                "description": "Rows."
              }
            },
            "additionalProperties": false
          },
          "lng": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "Degrees."
            },
            "description": "Point longitudes."
          },
          "lat": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "Degrees."
            },
            "description": "Point latitudes."
          },
          "val": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "Value."
            },
            "description": "Point values."
          }
        },
        "additionalProperties": false
      },
      "SubsurfaceSample": {
        "type": "object",
        "description": "Interpolated values.",
        "required": [
          "formation",
          "shl",
          "bhl",
          "values"
        ],
        "properties": {
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Target formation."
          },
          "shl": {
            "$ref": "#/components/schemas/LngLat"
          },
          "bhl": {
            "$ref": "#/components/schemas/LngLat"
          },
          "values": {
            "type": "object",
            "description": "Value per grid, distance per grid (`_novi_dist`: the mean of the read points' distances to the grid, each 0 inside it, in the config's units), bare property names for the formation and novi_min_grid_dist.",
            "additionalProperties": {
              "type": [
                "number",
                "null"
              ]
            }
          }
        },
        "additionalProperties": false
      },
      "SubsurfaceValue": {
        "type": "object",
        "description": "A value at the well and where it came from.",
        "required": [
          "value",
          "state"
        ],
        "properties": {
          "value": {
            "type": [
              "number",
              "null"
            ],
            "description": "The value, null when there is none."
          },
          "state": {
            "type": "string",
            "description": "mapped: interpolated from the set's grids; inferred: from the include=inferred rules; none: no value, with a reason.",
            "enum": [
              "mapped",
              "inferred",
              "none"
            ]
          },
          "grid_distance_mi": {
            "type": "number",
            "description": "The grid's distance from the well, mi: the mean over the points the set reads (its `subsurface_sampling` in GET /model-sets), each 0 inside it (GET /subsurface/sample's _novi_dist, in miles)."
          },
          "rule": {
            "type": "string",
            "description": "closure (rule 1) or offsets (rule 2).",
            "enum": [
              "closure",
              "offsets"
            ]
          },
          "grade": {
            "type": "string",
            "description": "Rule 4's grade.",
            "enum": [
              "high",
              "medium"
            ]
          },
          "offsets": {
            "type": "integer",
            "description": "Offset wells behind it."
          },
          "farthest_mi": {
            "type": "number",
            "description": "The farthest of them, mi."
          },
          "plus_minus": {
            "type": [
              "number",
              "null"
            ],
            "description": "The offsets' weighted standard deviation, in the value's unit, scaled with a gross rule 3 fit; null for a closure, with a reason."
          },
          "anchor": {
            "type": "string",
            "description": "An inferred top's anchor: the formation above whose mapped top it is measured from."
          },
          "scale": {
            "type": "number",
            "description": "Rule 3's factor, on each inferred value in a window it fit: a gross scaled by it, a top moved to the base above."
          },
          "reason": {
            "type": "string",
            "description": "Why it is none (after \"Not inferred:\", why the rules left it none), or for a closure why plus_minus is null."
          }
        },
        "additionalProperties": false
      },
      "WellSubsurfaceProperty": {
        "type": "object",
        "description": "A grid beyond the five fields, sampled at the well: mapped or none, never inferred.",
        "required": [
          "rock_property",
          "feature_name",
          "value",
          "state"
        ],
        "properties": {
          "rock_property": {
            "type": "string",
            "description": "The grid's rock property."
          },
          "feature_name": {
            "type": "string",
            "description": "The grid, as GET /subsurface names it."
          },
          "value": {
            "type": [
              "number",
              "null"
            ],
            "description": "The value, null when there is none."
          },
          "state": {
            "type": "string",
            "description": "mapped: interpolated from the set's grids; inferred: from the include=inferred rules; none: no value, with a reason.",
            "enum": [
              "mapped",
              "inferred",
              "none"
            ]
          },
          "grid_distance_mi": {
            "type": "number",
            "description": "The grid's distance from the well, mi: the mean over the points the set reads (its `subsurface_sampling` in GET /model-sets), each 0 inside it (GET /subsurface/sample's _novi_dist, in miles)."
          },
          "rule": {
            "type": "string",
            "description": "closure (rule 1) or offsets (rule 2).",
            "enum": [
              "closure",
              "offsets"
            ]
          },
          "grade": {
            "type": "string",
            "description": "Rule 4's grade.",
            "enum": [
              "high",
              "medium"
            ]
          },
          "offsets": {
            "type": "integer",
            "description": "Offset wells behind it."
          },
          "farthest_mi": {
            "type": "number",
            "description": "The farthest of them, mi."
          },
          "plus_minus": {
            "type": [
              "number",
              "null"
            ],
            "description": "The offsets' weighted standard deviation, in the value's unit, scaled with a gross rule 3 fit; null for a closure, with a reason."
          },
          "anchor": {
            "type": "string",
            "description": "An inferred top's anchor: the formation above whose mapped top it is measured from."
          },
          "scale": {
            "type": "number",
            "description": "Rule 3's factor, on each inferred value in a window it fit: a gross scaled by it, a top moved to the base above."
          },
          "reason": {
            "type": "string",
            "description": "Why it is none (after \"Not inferred:\", why the rules left it none), or for a closure why plus_minus is null."
          }
        },
        "additionalProperties": false
      },
      "WellSubsurface": {
        "type": "object",
        "description": "A well's subsurface column.",
        "required": [
          "wellbore_key",
          "formation",
          "datum",
          "formations",
          "well_wide",
          "landing"
        ],
        "properties": {
          "wellbore_key": {
            "type": "string",
            "description": "The well."
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "The well's own formation (its landing zone)."
          },
          "datum": {
            "$ref": "#/components/schemas/TvdDatum",
            "description": "The datum of every depth in this answer. subsea true: ft relative to sea level, negative below it, as the structure grids hold them (not a gun barrel's positive-down TVDss). Absent subsea (a depth pack that declares KB TVD structure grids): ft below the wells' KB, positive down. kb_offset_ft and elevation_source are the depth pack's, null without one."
          },
          "formations": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One formation at the well.",
              "required": [
                "formation",
                "label",
                "top_ft",
                "base_ft",
                "gross_ft",
                "net_ft",
                "bvi_avg",
                "bvi_net",
                "other"
              ],
              "properties": {
                "formation": {
                  "type": "string",
                  "description": "Formation."
                },
                "label": {
                  "type": "string",
                  "description": "Display name."
                },
                "top_ft": {
                  "$ref": "#/components/schemas/SubsurfaceValue",
                  "description": "Structure top, on the datum's axis."
                },
                "base_ft": {
                  "$ref": "#/components/schemas/SubsurfaceValue",
                  "description": "Top less gross thickness (plus, on a KB datum): mapped when both are, inferred (with the lower grade) when either is, none with a reason otherwise."
                },
                "gross_ft": {
                  "$ref": "#/components/schemas/SubsurfaceValue",
                  "description": "Gross thickness, ft."
                },
                "net_ft": {
                  "$ref": "#/components/schemas/SubsurfaceValue",
                  "description": "Net thickness, ft."
                },
                "bvi_avg": {
                  "$ref": "#/components/schemas/SubsurfaceValue",
                  "description": "BVI average, a fraction."
                },
                "bvi_net": {
                  "$ref": "#/components/schemas/SubsurfaceValue",
                  "description": "BVI net, a fraction."
                },
                "other": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WellSubsurfaceProperty"
                  },
                  "description": "The formation's other grids (porosity, saturation and the like), by rock property."
                }
              },
              "additionalProperties": false
            },
            "description": "Rock-column order, shallowest first; formations with no place in the column after."
          },
          "well_wide": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WellSubsurfaceProperty"
            },
            "description": "Grids whose formation is all: well-wide properties, not a formation."
          },
          "landing": {
            "type": "object",
            "description": "Where the well lands in its formation.",
            "required": [
              "formation",
              "depth_ft",
              "tvd_from",
              "source"
            ],
            "properties": {
              "formation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The well's formation."
              },
              "depth_ft": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The landing on the datum's axis, placed by its depth below its formation's top at the bottom hole (with survey stations in the set's depth pack: by POST /gun-barrels' survey or deeper-end landing); null with a reason."
              },
              "tvd_from": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "header",
                  "estimate",
                  "survey",
                  null
                ],
                "description": "header: its header TVD; estimate: the guarded estimate for a placeholder header; survey: its survey stations."
              },
              "source": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "How the depth was found, in words."
              },
              "reason": {
                "type": "string",
                "description": "Why there is no depth."
              }
            },
            "additionalProperties": false
          },
          "offset_wells": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A well an inferred value used.",
              "required": [
                "wellbore_key",
                "well_name",
                "distance_mi",
                "same_pad",
                "used"
              ],
              "properties": {
                "wellbore_key": {
                  "type": "string",
                  "description": "The offset well."
                },
                "well_name": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Its name."
                },
                "distance_mi": {
                  "type": "number",
                  "description": "Midpoint to midpoint, mi."
                },
                "same_pad": {
                  "type": "boolean",
                  "description": "On this well's pad (spacing pad id)."
                },
                "used": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "description": "One value it gave.",
                    "required": [
                      "formation",
                      "field",
                      "value"
                    ],
                    "properties": {
                      "formation": {
                        "type": "string",
                        "description": "Formation."
                      },
                      "field": {
                        "type": "string",
                        "description": "top_below_anchor_ft: its top's distance below the anchor's top; net_to_gross: its net over gross; else its value of that field.",
                        "enum": [
                          "top_below_anchor_ft",
                          "gross_ft",
                          "net_to_gross",
                          "bvi_avg",
                          "bvi_net"
                        ]
                      },
                      "value": {
                        "type": "number",
                        "description": "What it gave."
                      }
                    },
                    "additionalProperties": false
                  },
                  "description": "The values it gave, by formation."
                }
              },
              "additionalProperties": false
            },
            "description": "With include=inferred: every offset well an inferred value used, nearest first."
          },
          "unassigned": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "An interval no formation is given, or two are.",
              "required": [
                "kind",
                "above",
                "below",
                "top_ft",
                "base_ft",
                "thickness_ft"
              ],
              "properties": {
                "kind": {
                  "type": "string",
                  "description": "gap: the base is above the next top; overlap: the base runs past it.",
                  "enum": [
                    "gap",
                    "overlap"
                  ]
                },
                "above": {
                  "type": "string",
                  "description": "The formation whose base it is."
                },
                "below": {
                  "type": "string",
                  "description": "The next formation, whose top it is."
                },
                "top_ft": {
                  "type": "number",
                  "description": "Interval top, on the datum's axis."
                },
                "base_ft": {
                  "type": "number",
                  "description": "Interval base, on the datum's axis."
                },
                "thickness_ft": {
                  "type": "number",
                  "description": "Interval thickness, ft, positive."
                }
              },
              "additionalProperties": false
            },
            "description": "With include=inferred: every place where a base and the next top don't meet and one of them is inferred, as rule 3 left it."
          },
          "summary": {
            "type": "object",
            "description": "With include=inferred: counts.",
            "required": [
              "inferred",
              "refused",
              "offset_wells",
              "farthest_mi"
            ],
            "properties": {
              "inferred": {
                "type": "integer",
                "description": "Values inferred."
              },
              "refused": {
                "type": "integer",
                "description": "Values tried and left none."
              },
              "offset_wells": {
                "type": "integer",
                "description": "Offset wells used."
              },
              "farthest_mi": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The farthest one used, mi."
              }
            },
            "additionalProperties": false
          },
          "params": {
            "type": "object",
            "description": "With include=inferred: the fixed rule parameters.",
            "required": [
              "radius_mi",
              "max_offsets",
              "min_offsets",
              "weights",
              "fit_within",
              "high",
              "medium",
              "fault_blocks"
            ],
            "properties": {
              "radius_mi": {
                "type": "number",
                "description": "Offsets within this distance."
              },
              "max_offsets": {
                "type": "integer",
                "description": "At most this many per value."
              },
              "min_offsets": {
                "type": "integer",
                "description": "At least this many per value."
              },
              "weights": {
                "type": "string",
                "description": "Offset weights.",
                "enum": [
                  "inverse_distance_squared"
                ]
              },
              "fit_within": {
                "type": "number",
                "description": "Rule 3 scales a stack within this fraction of its gap."
              },
              "high": {
                "type": "object",
                "description": "Grade high.",
                "required": [
                  "min_offsets",
                  "within_mi",
                  "max_cv"
                ],
                "properties": {
                  "min_offsets": {
                    "type": "integer",
                    "description": "At least this many offsets."
                  },
                  "within_mi": {
                    "type": "number",
                    "description": "Every one within this, mi."
                  },
                  "max_cv": {
                    "type": "number",
                    "description": "CV under this."
                  }
                },
                "additionalProperties": false
              },
              "medium": {
                "type": "object",
                "description": "Grade medium.",
                "required": [
                  "min_offsets",
                  "within_mi",
                  "max_cv"
                ],
                "properties": {
                  "min_offsets": {
                    "type": "integer",
                    "description": "Offsets."
                  },
                  "within_mi": {
                    "type": "number",
                    "description": "mi."
                  },
                  "max_cv": {
                    "type": "number",
                    "description": "CV under this."
                  }
                },
                "additionalProperties": false
              },
              "fault_blocks": {
                "type": "string",
                "description": "Offsets are not limited by fault block."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "CompletionDefaults": {
        "type": "object",
        "description": "Default completions.",
        "required": [
          "fluid_bbl_per_ft",
          "proppant_lb_per_ft",
          "source",
          "wells",
          "window",
          "formations"
        ],
        "properties": {
          "fluid_bbl_per_ft": {
            "type": "number",
            "description": "Fluid, bbl per ft."
          },
          "proppant_lb_per_ft": {
            "type": "number",
            "description": "Proppant, lb per ft."
          },
          "source": {
            "type": "string",
            "description": "How the defaults were made."
          },
          "wells": {
            "type": "integer",
            "description": "Wells in the median."
          },
          "window": {
            "type": "object",
            "description": "Online window.",
            "required": [
              "start",
              "end",
              "days"
            ],
            "properties": {
              "start": {
                "type": "string",
                "description": "First online date.",
                "format": "date"
              },
              "end": {
                "type": "string",
                "description": "Last online date.",
                "format": "date"
              },
              "days": {
                "type": "integer",
                "description": "Window length."
              }
            },
            "additionalProperties": false
          },
          "formations": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One formation's medians over the same window.",
              "required": [
                "formation",
                "fluid_bbl_per_ft",
                "proppant_lb_per_ft",
                "wells",
                "source"
              ],
              "properties": {
                "formation": {
                  "type": "string",
                  "description": "Formation."
                },
                "fluid_bbl_per_ft": {
                  "type": "number",
                  "description": "Fluid, bbl per ft."
                },
                "proppant_lb_per_ft": {
                  "type": "number",
                  "description": "Proppant, lb per ft."
                },
                "wells": {
                  "type": "integer",
                  "description": "Wells in the median."
                },
                "source": {
                  "type": "string",
                  "description": "How the defaults were made."
                },
                "stage_length_ft": {
                  "type": "number",
                  "description": "Stage length, ft: the formation's median. Only on a model set whose models read it, where its wells give one."
                },
                "clusters_per_stage": {
                  "type": "number",
                  "description": "Clusters per stage: the formation's median, as stage_length_ft."
                },
                "frac_rate_bbl_per_min": {
                  "type": "number",
                  "description": "Frac rate, bbl/min: the formation's median, as stage_length_ft."
                },
                "sources": {
                  "type": "object",
                  "description": "How each stage median here was made; only beside one.",
                  "required": [],
                  "properties": {
                    "stage_length_ft": {
                      "type": "string",
                      "description": "How the median was made."
                    },
                    "clusters_per_stage": {
                      "type": "string",
                      "description": "How the median was made."
                    },
                    "frac_rate_bbl_per_min": {
                      "type": "string",
                      "description": "How the median was made."
                    }
                  },
                  "additionalProperties": false
                }
              },
              "additionalProperties": false
            },
            "description": "Formations with completions in the window; a blank design value uses its well's formation here, else the play-wide value."
          },
          "stage_length_ft": {
            "type": "number",
            "description": "Stage length, ft: the play's median. Only on a model set whose models read it, where its wells give one."
          },
          "clusters_per_stage": {
            "type": "number",
            "description": "Clusters per stage: the play's median, as stage_length_ft."
          },
          "frac_rate_bbl_per_min": {
            "type": "number",
            "description": "Frac rate, bbl/min: the play's median, as stage_length_ft."
          },
          "sources": {
            "type": "object",
            "description": "How each stage median here was made; only beside one.",
            "required": [],
            "properties": {
              "stage_length_ft": {
                "type": "string",
                "description": "How the median was made."
              },
              "clusters_per_stage": {
                "type": "string",
                "description": "How the median was made."
              },
              "frac_rate_bbl_per_min": {
                "type": "string",
                "description": "How the median was made."
              }
            },
            "additionalProperties": false
          },
          "inputs": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A completion field the set's models read.",
              "required": [
                "field",
                "label",
                "unit",
                "required",
                "default",
                "max",
                "model_inputs"
              ],
              "properties": {
                "field": {
                  "type": "string",
                  "description": "The design field.",
                  "enum": [
                    "fluid_bbl_per_ft",
                    "proppant_lb_per_ft",
                    "stage_length_ft",
                    "clusters_per_stage",
                    "frac_rate_bbl_per_min"
                  ]
                },
                "label": {
                  "type": "string",
                  "description": "A readable label."
                },
                "unit": {
                  "type": "string",
                  "description": "Its unit; empty for a count."
                },
                "required": {
                  "type": "boolean",
                  "description": "Whether a forecast needs a value: true for every field listed, which a blank fills from the defaults here; with none, the request is a 400 naming it."
                },
                "default": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "What a blank design value takes: the play's median here; null when the set's wells give none."
                },
                "max": {
                  "type": "number",
                  "description": "The exclusive upper bound a value takes, in the field's unit, as the design inputs' exclusiveMaximum; the lower bound is 0, also exclusive."
                },
                "model_inputs": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "description": "A model input."
                  },
                  "description": "The model inputs (GET /models features) the field feeds, as the statics a planned well's header derives from it."
                }
              },
              "additionalProperties": false
            },
            "description": "With include=inputs: the completion fields the set's models read, in the order designs list them; empty when the server has no model list."
          }
        },
        "additionalProperties": false
      },
      "TvdEstimateRequest": {
        "type": "object",
        "description": "TVD estimate request.",
        "required": [
          "wells"
        ],
        "properties": {
          "wells": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A well path.",
              "required": [
                "shl",
                "bhl",
                "formation"
              ],
              "properties": {
                "shl": {
                  "$ref": "#/components/schemas/LngLat"
                },
                "bhl": {
                  "$ref": "#/components/schemas/LngLat"
                },
                "formation": {
                  "type": "string",
                  "description": "Target formation."
                },
                "landing_fraction": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.\n\nThe top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.\n\nThe rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.\n\nTop and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.\n\nNeeds formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:\n\n- its formation has no grid there or no place in the column;\n- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);\n- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;\n- top and base averaged over the ends are under a foot apart: the zone pinches out.\n\nA well's inputs echo it when it was sent.",
                  "minimum": 0,
                  "maximum": 1
                }
              },
              "additionalProperties": false
            },
            "description": "Well paths.",
            "minItems": 1,
            "maxItems": 1000
          }
        },
        "additionalProperties": false
      },
      "TvdEstimateResponse": {
        "type": "object",
        "description": "TVD estimates.",
        "required": [
          "estimates"
        ],
        "properties": {
          "estimates": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "An estimate.",
              "required": [
                "index",
                "formation",
                "tvd_ft",
                "source",
                "method"
              ],
              "properties": {
                "index": {
                  "type": "integer",
                  "description": "Request position."
                },
                "formation": {
                  "type": "string",
                  "description": "Formation."
                },
                "tvd_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Estimated TVD, ft."
                },
                "source": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "How it was estimated."
                },
                "method": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "enum": [
                    "structure_grid",
                    "nearby_wells",
                    null
                  ],
                  "description": "structure_grid: grid top plus landing (or, with landing_fraction, that fraction of the thickness); nearby_wells: median TVD of nearby wells."
                },
                "formation_top_ft": {
                  "type": "integer",
                  "description": "Formation top at the well, ft below the set's TVD datum (tvd_datum; without it, the grid's subsea depth)."
                },
                "landing_below_top_ft": {
                  "type": "integer",
                  "description": "Median landing below the top, ft; not with landing_fraction."
                },
                "formation_base_ft": {
                  "type": "integer",
                  "description": "With landing_fraction: the formation's base at the well, in formation_top_ft's datum: the structure top of the next surface down the rock column with a grid there.\n\n- It is averaged over the same ends as formation_top_ft (those both grids reach).\n- When the set's depth pack names a thickness grid, it is formation_top_ft plus that grid instead.\n- With a depth pack, a formation with no gridded formation below it at the well takes formation_top_ft plus its novi_thickness_avg grid.\n- source names the surface or grid used."
                },
                "thickness_ft": {
                  "type": "integer",
                  "description": "With landing_fraction: base less top at the well, ft. tvd_ft is top + landing_fraction × thickness on the unrounded values, so it may be a foot off the sum of the rounded fields."
                },
                "wells_used": {
                  "type": "integer",
                  "description": "Wells behind the landing or median."
                },
                "wells_scope": {
                  "type": "string",
                  "description": "nearby (about 2 miles, or as source says when the search widened) or formation (formation-wide).",
                  "enum": [
                    "nearby",
                    "formation"
                  ]
                },
                "error": {
                  "type": "string",
                  "description": "Why there is no estimate."
                },
                "checks": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "description": "A check the estimate fails.",
                    "enum": [
                      "below_next_top",
                      "landing_far_from_formation"
                    ]
                  },
                  "description": "Present only when a check fires: the estimate may be off, so check it or send tvd_ft.\n\n- below_next_top: tvd_ft is at or below the next formation top down at this well, so the well may land in the formation below. Check the TVD.\n  - That top is the shallowest structure top of another formation (a depth pack's TVD-only grids included) deeper than this one's here, in formation_top_ft's datum, ordered by the grids at the well, not GET /formations.\n  - The two are averaged over only the ends (shl, bhl) both grids reach; a grid sharing no end with this formation's is left out.\n- landing_far_from_formation: structure_grid estimates with wells_scope nearby only, never on landing_fraction answers. Check the nearby wells.\n  - It fires when the nearby median landing before any move inside the zone (so it can differ from landing_below_top_ft) is outside the zone here, above the top or more than the thickness below it, and over that thickness from the formation-wide median of 3 or more wells.\n  - Thickness as landing_fraction measures it. A nearby landing inside the zone never fires it. Not checked without a formation-wide median or a thickness."
                },
                "landing_check": {
                  "type": "object",
                  "description": "With landing_far_from_formation only: nearby_ft is outside the zone, below 0 or above thickness_ft, and differs from formation_ft by more than thickness_ft. Rounded from the values compared, so they may be a foot off either limit.",
                  "required": [
                    "nearby_ft",
                    "formation_ft",
                    "thickness_ft"
                  ],
                  "properties": {
                    "nearby_ft": {
                      "type": "integer",
                      "description": "Nearby wells' median landing below the top before any move inside the zone, ft."
                    },
                    "formation_ft": {
                      "type": "integer",
                      "description": "Formation-wide median landing below the top from 3 or more wells, ft."
                    },
                    "thickness_ft": {
                      "type": "integer",
                      "description": "Formation thickness at the well, measured as landing_fraction measures it, ft."
                    }
                  },
                  "additionalProperties": false
                }
              },
              "additionalProperties": false
            },
            "description": "One per well."
          },
          "tvd_datum": {
            "$ref": "#/components/schemas/TvdDatum"
          }
        },
        "additionalProperties": false
      },
      "TvdDatum": {
        "type": "object",
        "description": "Optional: the TVD datum the set's depth pack puts tops in, present only for a model set with a depth pack. Absent: tops are the structure grid's own subsea depth. POST /gun-barrels with datum subsea adds subsea: true when it answers below sea level, as every answer does for a pack whose wells are subsea.",
        "required": [
          "datum",
          "kb_offset_ft",
          "elevation_source"
        ],
        "properties": {
          "datum": {
            "type": "string",
            "description": "kb: tops and TVDs are ft below the kelly bushing, the datum of the set's header TVDs. subsea true overrides it: every depth in that answer is ft below sea level, whatever datum says.",
            "enum": [
              "kb"
            ]
          },
          "kb_offset_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "The KB height above ground, ft, added to the ground elevation; when the set's structure grids already are KB TVDs, as the pack declares it (null if it declares none); null when the set's well TVDs already are ft below sea level."
          },
          "elevation_source": {
            "type": [
              "string",
              "null"
            ],
            "description": "Where the ground elevation comes from (as USGS 3DEP bare earth); null when the set's structure grids already are KB TVDs or its well TVDs already are ft below sea level."
          },
          "subsea": {
            "type": "boolean",
            "description": "Present, and true, when the answer's depths are ft below sea level (TVDss); absent, they are in `datum`. Label depths by subsea === true, not by datum, which stays kb in a subsea answer.\n\nPresent on a POST /gun-barrels answer to datum subsea for a pack with ground elevation. Also on every POST /tvd-estimates and POST /gun-barrels answer for a pack whose wells' TVDs already are subsea, with or without datum subsea: tops are the grid's own subsea depth and every TVD (header, estimated or sent) stays as it is."
          }
        },
        "additionalProperties": false
      },
      "GunBarrelRequest": {
        "type": "object",
        "description": "Wells to place: wells, keys or both, 200 in all, and optionally the line and the extras and the datum.",
        "required": [],
        "properties": {
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WellInput"
            },
            "description": "Drawn wells, as POST /forecasts takes them, without fluid_bbl_per_ft, proppant_lb_per_ft, decline or name: a gun barrel forecasts nothing, so they are a 400.",
            "minItems": 1,
            "maxItems": 200
          },
          "keys": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A wellbore key.",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "Existing wells, as GET /wells lists them; a repeat is answered once but counts toward the limit.",
            "minItems": 1,
            "maxItems": 200
          },
          "line": {
            "type": [
              "object",
              "null"
            ],
            "description": "Optional: the section line to measure about, instead of the one the laterals give. Send it to keep one line while the wells change (a pad's center and azimuth, so moving one row leaves the other rows' offsets as they were), or to cut a section along any line you draw, wells crossing it at an angle included. Absent or null, the line comes from the laterals.",
            "required": [
              "center",
              "azimuth_deg"
            ],
            "properties": {
              "center": {
                "$ref": "#/components/schemas/LngLat"
              },
              "azimuth_deg": {
                "type": "number",
                "description": "Degrees clockwise from north, -360 to 360; the answer gives it in [0, 360). along_ft is + toward it, across_ft + to its right.",
                "minimum": -360,
                "maximum": 360
              }
            },
            "additionalProperties": false
          },
          "include": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "ends: each well's heel_along_ft and toe_along_ft; tvd_from: each well's tvd_from.",
              "enum": [
                "ends",
                "tvd_from"
              ]
            },
            "description": "Optional: extras per well. Send ends to draw each lateral heel to toe, tvd_from to branch on where each TVD came from.",
            "maxItems": 2,
            "uniqueItems": true
          },
          "datum": {
            "type": "string",
            "description": "Optional: the depth datum to answer in. subsea: tvd_ft, top_ft and horizon tops in ft below sea level (TVDss), so wells compare across KB elevation; each field says how it is converted. kb or absent: the set's TVD datum.\n\nsubsea needs a depth pack with ground elevation: a pack of KB TVD grids, or a set without a pack, answers as without it (no tvd_datum.subsea). A pack whose wells already are subsea answers subsea either way. The tvd_ft you send on wells stays KB.",
            "enum": [
              "kb",
              "subsea"
            ]
          }
        },
        "additionalProperties": false,
        "anyOf": [
          {
            "required": [
              "wells"
            ],
            "properties": {
              "wells": true
            }
          },
          {
            "required": [
              "keys"
            ],
            "properties": {
              "keys": true
            }
          }
        ]
      },
      "GunBarrelHorizon": {
        "type": "object",
        "description": "A formation's structure top across the gun barrel.",
        "required": [
          "formation",
          "top_ft"
        ],
        "properties": {
          "formation": {
            "type": "string",
            "description": "Formation, as GET /formations names it."
          },
          "top_ft": {
            "type": "array",
            "items": {
              "type": [
                "integer",
                "null"
              ],
              "description": "ft below the set's TVD datum, as GunBarrelWell top_ft; null where there is no grid. With datum subsea (tvd_datum.subsea true), the grid's own subsea depth.\n\nIn KB, with a depth pack that has ground elevation: with the KB elevation at the placed wells' mean surface-hole along position, or averaged at the section's two ends (POST /gun-barrels says when); also null where there is no ground elevation at that point (on the two-end line, at either end)."
            },
            "description": "Its structure top at each sample_across_ft offset.",
            "minItems": 21,
            "maxItems": 21
          }
        },
        "additionalProperties": false
      },
      "GunBarrelWell": {
        "type": "object",
        "description": "A well in the gun barrel.",
        "required": [
          "kind",
          "formation",
          "across_ft",
          "along_ft",
          "tvd_ft",
          "tvd_source",
          "top_ft"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "description": "drawn (from wells) or existing (from keys).",
            "enum": [
              "drawn",
              "existing"
            ]
          },
          "index": {
            "type": "integer",
            "description": "Drawn: its index in wells.",
            "minimum": 0
          },
          "wellbore_key": {
            "type": "string",
            "description": "Existing: its wellbore key."
          },
          "well_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Existing: its name."
          },
          "first_prod": {
            "type": [
              "string",
              "null"
            ],
            "description": "Existing: its first production, to order vintages.",
            "format": "date"
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its formation."
          },
          "across_ft": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Its lateral midpoint's offset square to the line, ft, + right looking along azimuth_deg; null without both ends."
          },
          "along_ft": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Its lateral midpoint's offset along the line, ft, + in the direction of azimuth_deg; null without both ends."
          },
          "heel_along_ft": {
            "type": [
              "integer",
              "null"
            ],
            "description": "With include ends: its lateral's heel on along_ft's axis, ft: a drawn well's heel, else its shl, an existing well's header heel, else its surface hole; null without both ends."
          },
          "toe_along_ft": {
            "type": [
              "integer",
              "null"
            ],
            "description": "With include ends: its lateral's toe (bottom hole) on along_ft's axis, ft; less than heel_along_ft for a well drilled against azimuth_deg; null without both ends."
          },
          "tvd_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "TVD, ft: as a forecast would use it (drawn) or the header's tvd_td (existing); null when there is none.\n\n- Existing: the estimate instead when tvd_td is a multiple of 500 ft; drawn by its survey stations, or by tvd_td at its deeper end, in a set whose depth pack carries them.\n- With datum subsea (tvd_datum.subsea true): that TVD less the KB elevation at its surface hole, ft below sea level, to the foot; null with an error where the pack has no ground elevation there or the well has no surface hole location."
          },
          "tvd_source": {
            "type": [
              "string",
              "null"
            ],
            "description": "input, how it was placed or estimated, or header; null without tvd_ft."
          },
          "tvd_from": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "input",
              "landing",
              "estimate",
              "header",
              "survey",
              null
            ],
            "description": "With include tvd_from: where tvd_ft came from, as a code; null without tvd_ft.\n\n- input: tvd_ft sent.\n- landing: the formation top + landing_below_top_ft sent, or landing_fraction of its thickness.\n- estimate: POST /tvd-estimates' estimate; on an existing well, one replacing a placeholder tvd_td, or a tvd_td outside its formation moved a foot inside it (sets labelled from their grids).\n- header: an existing well's tvd_td, read at its deeper end where the set's depth pack has survey stations and its header TVDs are their wells' deepest stations.\n- survey: an existing well drawn by its survey stations."
          },
          "top_ft": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Its formation's structure top at the well, ft below the set's TVD datum (tvd_datum: its KB, so tvd_ft − top_ft is the landing; without it, the grid's subsea depth); null without a formation or grid there, or, with a depth pack in KB, no ground elevation at its surface hole. With datum subsea (tvd_datum.subsea true): the grid's own subsea depth, so tvd_ft − top_ft is still the landing."
          },
          "error": {
            "type": "string",
            "description": "Why tvd_ft or the offsets are null."
          }
        },
        "additionalProperties": false
      },
      "GunBarrel": {
        "type": "object",
        "description": "A gun barrel: the line through center (across 0, along 0) at azimuth_deg, the horizons and the wells.",
        "required": [
          "azimuth_deg",
          "center",
          "along_range_ft",
          "sample_across_ft",
          "horizons",
          "wells"
        ],
        "properties": {
          "azimuth_deg": {
            "type": "number",
            "description": "The line's direction, degrees clockwise from north, in [0, 360): the laterals' mean heel to toe, to 0.1, or line.azimuth_deg brought into that range (as sent when it already is).",
            "minimum": 0,
            "exclusiveMaximum": 360
          },
          "center": {
            "$ref": "#/components/schemas/LngLat"
          },
          "along_range_ft": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "ft along the line."
            },
            "description": "[from, to]: where the laterals start and end along the line, ft from center; horizons are averaged at these two.",
            "minItems": 2,
            "maxItems": 2
          },
          "sample_across_ft": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "ft across, + right looking along azimuth_deg."
            },
            "description": "21 offsets, evenly spaced from the leftmost lateral less a margin to the rightmost plus it (the larger of 660 ft and a tenth of the wells' spread across).",
            "minItems": 21,
            "maxItems": 21
          },
          "horizons": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GunBarrelHorizon"
            },
            "description": "Every formation with a structure grid (a depth pack's TVD-only ones included), top to bottom in the rock column that landing_fraction takes its base from; POST /gun-barrels says the order within one surface, outside the column, and when the column can't be built. Empty without grids."
          },
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GunBarrelWell"
            },
            "description": "The wells, drawn first, in request order."
          },
          "tvd_datum": {
            "$ref": "#/components/schemas/TvdDatum"
          }
        },
        "additionalProperties": false
      },
      "LandGridLine": {
        "type": "object",
        "description": "One kind of survey line.",
        "required": [
          "type",
          "geometry",
          "properties"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Feature.",
            "enum": [
              "Feature"
            ]
          },
          "geometry": {
            "type": "object",
            "description": "Every line of this kind whose extent overlaps the bbox, whole.",
            "required": [
              "type",
              "coordinates"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "MultiLineString.",
                "enum": [
                  "MultiLineString"
                ]
              },
              "coordinates": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/LngLat"
                  },
                  "description": "A line, in order.",
                  "minItems": 2
                },
                "description": "The lines."
              }
            },
            "additionalProperties": false
          },
          "properties": {
            "type": "object",
            "description": "What the lines are.",
            "required": [
              "kind",
              "line"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "description": "line.",
                "enum": [
                  "line"
                ]
              },
              "line": {
                "type": "string",
                "description": "county: a county boundary; block: a block line; section: a section or survey line; abstract: an abstract division line.",
                "enum": [
                  "county",
                  "block",
                  "section",
                  "abstract"
                ]
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "LandGridLabel": {
        "type": "object",
        "description": "A survey label.",
        "required": [
          "type",
          "geometry",
          "properties"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Feature.",
            "enum": [
              "Feature"
            ]
          },
          "geometry": {
            "type": "object",
            "description": "Where the label goes: inside its largest parcel.",
            "required": [
              "type",
              "coordinates"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "Point.",
                "enum": [
                  "Point"
                ]
              },
              "coordinates": {
                "$ref": "#/components/schemas/LngLat"
              }
            },
            "additionalProperties": false
          },
          "properties": {
            "type": "object",
            "description": "The label and the parcel it names.",
            "required": [
              "kind",
              "level",
              "text",
              "county_fips",
              "abstract",
              "survey",
              "block",
              "section"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "description": "label.",
                "enum": [
                  "label"
                ]
              },
              "level": {
                "type": "string",
                "description": "The level the label belongs to, as asked.",
                "enum": [
                  "block",
                  "section",
                  "abstract"
                ]
              },
              "text": {
                "type": "string",
                "description": "What to show: \"<survey> Blk <block>\" (once in each county a block spans), the section number (else the survey name), or \"A-\" and the abstract number."
              },
              "county_fips": {
                "type": "string",
                "description": "Texas county FIPS code (3 digits): for an abstract the county it is recorded in, else the county it lies in.",
                "pattern": "^\\d{3}$"
              },
              "abstract": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Abstract number, without \"A-\" (abstract labels)."
              },
              "survey": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Survey name, as the RRC writes it."
              },
              "block": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Block, as the RRC writes it (block and finer labels)."
              },
              "section": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Section number (section and abstract labels)."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "LandGrid": {
        "type": "object",
        "description": "Survey lines and labels in a bbox: a GeoJSON FeatureCollection.",
        "required": [
          "type",
          "level",
          "bbox",
          "coverage",
          "source",
          "features"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "FeatureCollection.",
            "enum": [
              "FeatureCollection"
            ]
          },
          "level": {
            "type": "string",
            "description": "The level asked for.",
            "enum": [
              "block",
              "section",
              "abstract"
            ]
          },
          "bbox": {
            "type": "array",
            "items": {
              "type": "number",
              "description": "Degrees."
            },
            "description": "The bbox asked for, as [west, south, east, north].",
            "minItems": 4,
            "maxItems": 4
          },
          "coverage": {
            "type": "object",
            "description": "Where the grid has data.",
            "required": [
              "state",
              "counties"
            ],
            "properties": {
              "state": {
                "type": "string",
                "description": "TX.",
                "enum": [
                  "TX"
                ]
              },
              "counties": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "County FIPS code.",
                  "pattern": "^\\d{3}$"
                },
                "description": "The counties the grid holds, ascending, whatever the bbox."
              }
            },
            "additionalProperties": false
          },
          "source": {
            "type": "string",
            "description": "Where the grid comes from and its date (the RRC grid's download date, the sample's as-of date), how it was shifted, and that it is not a legal survey."
          },
          "features": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/LandGridLine"
                },
                {
                  "$ref": "#/components/schemas/LandGridLabel"
                }
              ]
            },
            "description": "Lines first, one feature per kind from county to abstract, then labels."
          }
        },
        "additionalProperties": false
      },
      "FillLayoutRequest": {
        "type": "object",
        "description": "Fill layout request: polygon or area, and spacing_ft or benches.",
        "required": [],
        "properties": {
          "polygon": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LngLat"
            },
            "description": "Area corners, in order (closing point optional). Edges that cross are a 400.",
            "minItems": 3,
            "maxItems": 500
          },
          "azimuth_deg": {
            "type": "number",
            "description": "Direction wells are drilled, degrees clockwise from north.",
            "minimum": -360,
            "maximum": 360,
            "default": 0
          },
          "spacing_ft": {
            "type": "number",
            "description": "Distance between wells, ft.",
            "minimum": 100,
            "maximum": 10000
          },
          "lateral_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Lateral length, ft; null or absent runs each well edge to edge.",
            "minimum": 1000,
            "maximum": 30000
          },
          "setback_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Feet the wells keep from the unit's outline and holes, from every point of a well in any direction; with setback_end_ft, measured across the well (square to the azimuth).",
            "minimum": 0,
            "maximum": 2640,
            "default": 0
          },
          "area": {
            "$ref": "#/components/schemas/UnitArea",
            "description": "Instead of polygon: the unit as a GeoJSON Polygon or MultiPolygon in WGS 84, an area's geometry from POST /areas or what POST /units/summary takes. Holes are left out and each part is filled on its own; rings follow the unit scope's rules (POST /units/summary). Every edge costs work on every line, so a detailed outline may be too complex to fill: simplify it (as POST /areas' fill.polygon is)."
          },
          "setback_end_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Feet each well's heel and toe keep from the outline and holes, in a straight line; the rest of the well may pass closer as long as setback_ft holds across it. With lateral_length_ft, a piece whose heel or toe would fall closer is left out. Every edge gets both rules, whatever its angle.",
            "minimum": 0,
            "maximum": 2640
          },
          "min_lateral_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Shortest well, ft: every edge-to-edge chord at least this long is a well, instead of those within 95% of the longest. Not with lateral_length_ft.\n\nA kept chord longer than 30,000 ft between the rounded ends splits into the fewest equal wells of at most 30,000 ft, toe meeting heel; a split piece shorter than min_lateral_ft is left out, so such a chord may give no well.",
            "minimum": 1000,
            "maximum": 30000
          },
          "standoff_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Least distance from every lateral to the existing laterals (heel, else surface hole, to bottom hole) in its formation that lie in the unit or within standoff_ft of it, ft. Needs a formation for every bench.",
            "minimum": 0,
            "maximum": 5280
          },
          "wells_per_pad": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Groups the wells into pads of this many, numbered from 0 in each well's pad; a pad never spans two parts or tiers, so the last of each may hold fewer.\n\nA fill's pads only label wells: each well keeps its surface hole and the request's TIL date. To set a pad's values, post the fill's `wells` with `pads`. POST /plans keeps pad keys: with `layout`, the 1-based pad number as text; with `layouts`, the 1-based layout number, a hyphen, then the 1-based pad number. Without wells_per_pad, laid-out wells have no pad key. To price a pad, send its wells (a plan's layout echo `pads`) as a plan scenario's `wells` in POST /economics.",
            "minimum": 1,
            "maximum": 50
          },
          "lateral_check": {
            "type": "boolean",
            "description": "Mark each well whose lateral is outside the model's training range, as a forecast's checks would flag it. Show the mark beside any lateral or volume you quote for a marked well.\n\nThe model is the first served stream's (oil, else gas, else water) and the range its novi_lateral_length p01 to p99 in ft; a well is marked past it by more than 5% of that range, its lateral measured between its returned ends. Only on POST /layouts/fill: a forecast's or plan's wells carry checks.",
            "default": false
          },
          "benches": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A bench: spacing_ft or wells_per_section, not both.",
              "required": [],
              "properties": {
                "spacing_ft": {
                  "type": "number",
                  "description": "Distance between the bench's wells, ft. Not with wells_per_section.",
                  "minimum": 100,
                  "maximum": 10000
                },
                "wells_per_section": {
                  "type": "number",
                  "description": "Instead of spacing_ft: wells per section, so spacing is 5,280 ft / wells_per_section (within spacing_ft's bounds).",
                  "minimum": 0.528,
                  "maximum": 52.8
                },
                "offset_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Shifts the bench's lines across the azimuth, ft (+ to the right looking along it), to stagger benches; 0, null or absent is no shift.\n\nLines pushed outside the area less setback_ft are dropped, not wrapped round, so a half-spacing stagger often holds one well fewer. A part with a non-zero offset isn't evened out, and in POST /plans' layouts no layout of the plan is, so a stagger set across layouts holds.",
                  "minimum": -10000,
                  "maximum": 10000,
                  "default": 0
                },
                "formation": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The bench's formation (case-insensitive; GET /formations lists them): its wells carry it, and standoff_ft stands off its laterals. Default the request's formation."
                }
              },
              "additionalProperties": false,
              "oneOf": [
                {
                  "required": [
                    "spacing_ft"
                  ],
                  "properties": {
                    "spacing_ft": true
                  }
                },
                {
                  "required": [
                    "wells_per_section"
                  ],
                  "properties": {
                    "wells_per_section": true
                  }
                }
              ]
            },
            "description": "Instead of spacing_ft: benches filled together, each with its own spacing, offset and formation.",
            "minItems": 1,
            "maxItems": 10
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "The wells' formation (case-insensitive; GET /formations lists them), which each well then carries; standoff_ft needs it without benches."
          }
        },
        "additionalProperties": false,
        "allOf": [
          {
            "oneOf": [
              {
                "required": [
                  "area"
                ],
                "properties": {
                  "area": true
                }
              },
              {
                "required": [
                  "polygon"
                ],
                "properties": {
                  "polygon": true
                }
              }
            ]
          },
          {
            "oneOf": [
              {
                "required": [
                  "spacing_ft"
                ],
                "properties": {
                  "spacing_ft": true
                }
              },
              {
                "required": [
                  "benches"
                ],
                "properties": {
                  "benches": true
                }
              }
            ]
          }
        ]
      },
      "FillLayoutResponse": {
        "type": "object",
        "description": "Filled layout.",
        "required": [
          "count",
          "azimuth_deg",
          "lateral_length_ft",
          "wells"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "Wells."
          },
          "azimuth_deg": {
            "type": "number",
            "description": "Azimuth used."
          },
          "spacing_ft": {
            "type": "number",
            "description": "Spacing used; left out with benches."
          },
          "lateral_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Length used, or null for edge to edge."
          },
          "setback_ft": {
            "type": "number",
            "description": "Setback used, ft; only when the request sent one."
          },
          "setback_end_ft": {
            "type": "number",
            "description": "End setback used, ft; only when sent."
          },
          "min_lateral_ft": {
            "type": "number",
            "description": "Shortest well used, ft; only when sent. No returned well is shorter: split pieces shorter than it are left out."
          },
          "standoff_ft": {
            "type": "number",
            "description": "Standoff used, ft; only when sent."
          },
          "standoff_wells": {
            "type": "integer",
            "description": "With standoff_ft: how many existing laterals POST /wells/search finds within standoff_ft of the unit (match lateral, in the wells' formations). The fill also clears laterals just past standoff_ft by that measure.",
            "minimum": 0
          },
          "wells_per_pad": {
            "type": "integer",
            "description": "Wells per pad; only when sent."
          },
          "wells_per_section": {
            "type": "number",
            "description": "With benches: their wells_per_section added up, the unit's total."
          },
          "lateral_check": {
            "description": "With lateral_check: true: the range the wells were marked against, or why there is none. Show the mark beside any lateral or volume you quote for a marked well. The model is the model set's first served stream's (oil, else gas, else water), so `model_num` and `reason` read that model where they say oil.",
            "oneOf": [
              {
                "type": "object",
                "description": "The range.",
                "required": [
                  "available",
                  "model_num",
                  "feature",
                  "low_ft",
                  "high_ft",
                  "margin_ft",
                  "outside"
                ],
                "properties": {
                  "available": {
                    "type": "boolean",
                    "description": "The range was found.",
                    "const": true
                  },
                  "model_num": {
                    "type": "string",
                    "description": "The served oil model whose training range was used."
                  },
                  "feature": {
                    "type": "string",
                    "description": "The model input checked.",
                    "const": "novi_lateral_length"
                  },
                  "low_ft": {
                    "type": "number",
                    "description": "Its training 1st percentile, ft, as GET /models gives it."
                  },
                  "high_ft": {
                    "type": "number",
                    "description": "Its training 99th percentile, ft, as GET /models gives it."
                  },
                  "margin_ft": {
                    "type": "number",
                    "description": "5% of high_ft minus low_ft: a well is marked only when its lateral is more than this below low_ft or above high_ft."
                  },
                  "outside": {
                    "type": "integer",
                    "description": "Wells marked above or below.",
                    "minimum": 0
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "object",
                "description": "No range.",
                "required": [
                  "available",
                  "reason"
                ],
                "properties": {
                  "available": {
                    "type": "boolean",
                    "description": "No range, so no well carries lateral_outside.",
                    "const": false
                  },
                  "reason": {
                    "type": "string",
                    "description": "Why: no oil model, no training statistics for it, or no novi_lateral_length range in them."
                  }
                },
                "additionalProperties": false
              }
            ]
          },
          "pads": {
            "type": "integer",
            "description": "With wells_per_pad: the pads.",
            "minimum": 0
          },
          "benches": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A bench as filled.",
              "required": [
                "spacing_ft",
                "wells_per_section",
                "offset_ft",
                "formation",
                "count"
              ],
              "properties": {
                "spacing_ft": {
                  "type": "number",
                  "description": "Spacing used, ft."
                },
                "wells_per_section": {
                  "type": "number",
                  "description": "5,280 ft / spacing_ft, or as sent."
                },
                "offset_ft": {
                  "type": "number",
                  "description": "Offset used, ft."
                },
                "formation": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The bench's formation, or null when none was sent."
                },
                "count": {
                  "type": "integer",
                  "description": "Wells in the bench.",
                  "minimum": 0
                }
              },
              "additionalProperties": false
            },
            "description": "With benches: each bench as filled."
          },
          "formation": {
            "type": "string",
            "description": "The request's formation, as GET /formations names it; only when sent."
          },
          "wells": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A well.",
              "required": [
                "shl",
                "bhl",
                "lateral_length_ft"
              ],
              "properties": {
                "shl": {
                  "$ref": "#/components/schemas/LngLat"
                },
                "bhl": {
                  "$ref": "#/components/schemas/LngLat"
                },
                "lateral_length_ft": {
                  "type": "integer",
                  "description": "Lateral length, ft."
                },
                "formation": {
                  "type": "string",
                  "description": "Its bench's formation, else the request's; only when one is known."
                },
                "part": {
                  "type": "integer",
                  "description": "With area: the index of its part in the MultiPolygon, 0 in a Polygon.",
                  "minimum": 0
                },
                "bench": {
                  "type": "integer",
                  "description": "With benches: its bench's index.",
                  "minimum": 0
                },
                "pad": {
                  "type": "integer",
                  "description": "With wells_per_pad: its pad, from 0.",
                  "minimum": 0
                },
                "lateral_outside": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Above or below the training lateral range past its margin, else null; present only with lateral_check and an available range.",
                  "enum": [
                    "above",
                    "below",
                    null
                  ]
                }
              },
              "additionalProperties": false
            },
            "description": "Wells, left to right looking along the azimuth (west to east for an azimuth strictly between -90 and 90 or past 270 either way, the default 0 included); with area or benches, part by part, then bench by bench."
          }
        },
        "additionalProperties": false
      },
      "FillAreasRequest": {
        "type": "object",
        "description": "Fill areas request: areas, lateral_length_ft, and spacing_ft or benches.",
        "required": [
          "areas",
          "lateral_length_ft"
        ],
        "properties": {
          "areas": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "An area to fill.",
              "required": [
                "area"
              ],
              "properties": {
                "id": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Echoed in the answer; each once. Absent or null, the entry's index.",
                  "minimum": 0,
                  "maximum": 2147483647
                },
                "area": {
                  "$ref": "#/components/schemas/UnitArea",
                  "description": "The area as a GeoJSON Polygon or MultiPolygon in WGS 84 with only type and coordinates: an area's geometry from POST /areas, or your own. A ring POST /layouts/fill's area would refuse skips the area as degenerate."
                }
              },
              "additionalProperties": false
            },
            "description": "The areas: at most 200,000 vertices in all.",
            "minItems": 1,
            "maxItems": 5000
          },
          "lateral_length_ft": {
            "type": "number",
            "description": "The length each well aims for, ft (5,280 is a mile). Required.",
            "minimum": 1000,
            "maximum": 30000
          },
          "min_lateral_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "The shortest well, ft, at most lateral_length_ft: a stretch takes as many wells of lateral_length_ft as fit, centred, or one more, all equal, when the land they leave is at least this long. Absent or null, 85% of lateral_length_ft to the foot, at least 1,000.",
            "minimum": 1000,
            "maximum": 30000
          },
          "azimuth_deg": {
            "type": [
              "number",
              "null"
            ],
            "description": "Every group's direction, degrees clockwise from north (wells drilled toward it). Absent or null, each group's long axis.",
            "minimum": -360,
            "maximum": 360
          },
          "spacing_ft": {
            "type": "number",
            "description": "Distance between wells, ft.",
            "minimum": 100,
            "maximum": 10000
          },
          "benches": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A bench: spacing_ft or wells_per_section, not both.",
              "required": [],
              "properties": {
                "spacing_ft": {
                  "type": "number",
                  "description": "Distance between the bench's wells, ft. Not with wells_per_section.",
                  "minimum": 100,
                  "maximum": 10000
                },
                "wells_per_section": {
                  "type": "number",
                  "description": "Instead of spacing_ft: wells per section, so spacing is 5,280 ft / wells_per_section (within spacing_ft's bounds).",
                  "minimum": 0.528,
                  "maximum": 52.8
                },
                "offset_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Shifts the bench's lines across the azimuth, ft (+ to the right looking along it), to stagger benches; 0, null or absent is no shift.\n\nLines pushed outside the area less setback_ft are dropped, not wrapped round, so a half-spacing stagger often holds one well fewer. A part with a non-zero offset isn't evened out, and in POST /plans' layouts no layout of the plan is, so a stagger set across layouts holds.",
                  "minimum": -10000,
                  "maximum": 10000,
                  "default": 0
                },
                "formation": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The bench's formation (case-insensitive; GET /formations lists them): its wells carry it. Default the request's formation."
                }
              },
              "additionalProperties": false,
              "oneOf": [
                {
                  "required": [
                    "spacing_ft"
                  ],
                  "properties": {
                    "spacing_ft": true
                  }
                },
                {
                  "required": [
                    "wells_per_section"
                  ],
                  "properties": {
                    "wells_per_section": true
                  }
                }
              ]
            },
            "description": "Instead of spacing_ft: benches filled together, each with its own spacing, offset and formation.",
            "minItems": 1,
            "maxItems": 10
          },
          "setback_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Feet the wells keep from each group's outer edges and holes, not from the lines between its areas, as POST /layouts/fill keeps them from an area's.",
            "minimum": 0,
            "maximum": 2640
          },
          "setback_end_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Feet each well's heel and toe keep from each group's outer edges and holes, as POST /layouts/fill keeps them from an area's.",
            "minimum": 0,
            "maximum": 2640
          },
          "wells_per_pad": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Groups each group's wells into pads of this many, as POST /layouts/fill does; pads number on across groups, so each is unique in the answer.",
            "minimum": 1,
            "maximum": 50
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "The wells' formation (case-insensitive; GET /formations lists them), which each well then carries."
          }
        },
        "additionalProperties": false,
        "oneOf": [
          {
            "required": [
              "spacing_ft"
            ],
            "properties": {
              "spacing_ft": true
            }
          },
          {
            "required": [
              "benches"
            ],
            "properties": {
              "benches": true
            }
          }
        ]
      },
      "FillAreasResponse": {
        "type": "object",
        "description": "Wells over many areas.",
        "required": [
          "count",
          "lateral_length_ft",
          "min_lateral_ft",
          "azimuth_deg",
          "join",
          "max_wells",
          "areas",
          "groups",
          "skipped",
          "wells"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "Wells.",
            "minimum": 0
          },
          "lateral_length_ft": {
            "type": "number",
            "description": "Length used, ft."
          },
          "min_lateral_ft": {
            "type": "number",
            "description": "Shortest well used, ft: as sent, or the default."
          },
          "azimuth_deg": {
            "type": [
              "number",
              "null"
            ],
            "description": "The request's azimuth_deg, or null when each group ran along its own (groups[].azimuth_deg)."
          },
          "spacing_ft": {
            "type": "number",
            "description": "Spacing used; left out with benches."
          },
          "setback_ft": {
            "type": "number",
            "description": "Setback used, ft; only when sent."
          },
          "setback_end_ft": {
            "type": "number",
            "description": "End setback used, ft; only when sent."
          },
          "wells_per_pad": {
            "type": "integer",
            "description": "Wells per pad; only when sent."
          },
          "pads": {
            "type": "integer",
            "description": "With wells_per_pad: the pads, across groups.",
            "minimum": 0
          },
          "wells_per_section": {
            "type": "number",
            "description": "With benches: their wells_per_section added up."
          },
          "benches": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A bench as filled; count is its wells across groups.",
              "required": [
                "spacing_ft",
                "wells_per_section",
                "offset_ft",
                "formation",
                "count"
              ],
              "properties": {
                "spacing_ft": {
                  "type": "number",
                  "description": "Spacing used, ft."
                },
                "wells_per_section": {
                  "type": "number",
                  "description": "5,280 ft / spacing_ft, or as sent."
                },
                "offset_ft": {
                  "type": "number",
                  "description": "Offset used, ft."
                },
                "formation": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The bench's formation, or null when none was sent."
                },
                "count": {
                  "type": "integer",
                  "description": "Wells in the bench.",
                  "minimum": 0
                }
              },
              "additionalProperties": false
            },
            "description": "With benches: each bench as filled."
          },
          "formation": {
            "type": "string",
            "description": "The request's formation, as GET /formations names it; only when sent."
          },
          "join": {
            "type": "object",
            "description": "The distances that join parts into one piece of land.",
            "required": [
              "within_ft",
              "min_shared_ft"
            ],
            "properties": {
              "within_ft": {
                "type": "number",
                "description": "Edges and stretches this close count as touching, ft."
              },
              "min_shared_ft": {
                "type": "number",
                "description": "The least shared stretch that joins two parts, ft."
              }
            },
            "additionalProperties": false
          },
          "max_wells": {
            "type": "integer",
            "description": "The most wells the answer holds: the lesser of GET /dataset limits.plan_wells and 10,000.",
            "minimum": 1
          },
          "areas": {
            "type": "object",
            "description": "What became of the areas: sent is used plus the skipped counts.",
            "required": [
              "sent",
              "used",
              "skipped"
            ],
            "properties": {
              "sent": {
                "type": "integer",
                "description": "Areas sent.",
                "minimum": 1
              },
              "used": {
                "type": "integer",
                "description": "Areas some well runs through.",
                "minimum": 0
              },
              "skipped": {
                "type": "object",
                "description": "Skipped areas by reason.",
                "required": [
                  "outside_dataset",
                  "degenerate",
                  "too_small",
                  "over_limit"
                ],
                "properties": {
                  "outside_dataset": {
                    "type": "integer",
                    "description": "Areas skipped as outside_dataset.",
                    "minimum": 0
                  },
                  "degenerate": {
                    "type": "integer",
                    "description": "Areas skipped as degenerate.",
                    "minimum": 0
                  },
                  "too_small": {
                    "type": "integer",
                    "description": "Areas skipped as too_small.",
                    "minimum": 0
                  },
                  "over_limit": {
                    "type": "integer",
                    "description": "Areas skipped as over_limit.",
                    "minimum": 0
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A piece of land that laid wells.",
              "required": [
                "areas",
                "azimuth_deg",
                "first",
                "count"
              ],
              "properties": {
                "areas": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "description": "An area's id.",
                    "minimum": 0
                  },
                  "description": "The group's areas' ids, in request order; a MultiPolygon whose parts fall in several groups is in each."
                },
                "azimuth_deg": {
                  "type": "number",
                  "description": "The group's azimuth, degrees: the request's azimuth_deg as sent, else measured on the group's flat grid to 0.001. Sent back as azimuth_deg, it lays the same wells."
                },
                "first": {
                  "type": "integer",
                  "description": "Its first well's index in wells.",
                  "minimum": 0
                },
                "count": {
                  "type": "integer",
                  "description": "Its wells.",
                  "minimum": 1
                }
              },
              "additionalProperties": false
            },
            "description": "The groups that laid wells, in order; wells[].group indexes it."
          },
          "skipped": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A skipped area.",
              "required": [
                "id",
                "reason"
              ],
              "properties": {
                "id": {
                  "type": "integer",
                  "description": "The area's id.",
                  "minimum": 0
                },
                "reason": {
                  "type": "string",
                  "description": "outside_dataset: its box misses the dataset's; degenerate: a ring a fill refuses; too_small: no well runs through it; over_limit: its group would pass the well limit or the fill work, or its holes need more checking than one request has left.",
                  "enum": [
                    "outside_dataset",
                    "degenerate",
                    "too_small",
                    "over_limit"
                  ]
                },
                "detail": {
                  "type": "string",
                  "description": "degenerate: the fault; over_limit: the limit."
                }
              },
              "additionalProperties": false
            },
            "description": "Each skipped area once, in request order."
          },
          "wells": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A well.",
              "required": [
                "shl",
                "bhl",
                "lateral_length_ft",
                "group",
                "areas"
              ],
              "properties": {
                "shl": {
                  "$ref": "#/components/schemas/LngLat"
                },
                "bhl": {
                  "$ref": "#/components/schemas/LngLat"
                },
                "lateral_length_ft": {
                  "type": "integer",
                  "description": "Lateral length, ft."
                },
                "formation": {
                  "type": "string",
                  "description": "Its bench's formation, else the request's; only when one is known."
                },
                "bench": {
                  "type": "integer",
                  "description": "With benches: its bench's index.",
                  "minimum": 0
                },
                "pad": {
                  "type": "integer",
                  "description": "With wells_per_pad: its pad, from 0, unique across groups.",
                  "minimum": 0
                },
                "group": {
                  "type": "integer",
                  "description": "Its group's index in groups.",
                  "minimum": 0
                },
                "areas": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "description": "An area's id.",
                    "minimum": 0
                  },
                  "description": "The areas it runs through, heel to toe."
                }
              },
              "additionalProperties": false
            },
            "description": "Wells, group by group, then bench by bench."
          }
        },
        "additionalProperties": false
      },
      "LayoutSource": {
        "type": "object",
        "description": "Lay the wells out on the server with POST /layouts/fill's parameters instead of sending them. Send `wells` or `layout`, not both.\n\n- Every well lands in `formation` with the layout's `tvd_ft`, `landing_below_top_ft` or `landing_fraction` and `til_date`. With `benches`, each bench names its wells' formation and may set its own landing field; the layout then sets none (400 naming the one sent).\n- A layout and each bench may set `fluid_bbl_per_ft` and `proppant_lb_per_ft`.\n- The response's `layout` says what was laid out, and each well's `inputs` carries its ends.\n- Errors index wells as POST /layouts/fill orders them: `wells[k]` for a well that can't be estimated, `layout.wells[k].bhl` for a lateral outside 100 to 50,000 ft.",
        "required": [],
        "properties": {
          "polygon": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LngLat"
            },
            "description": "Area corners, in order (closing point optional). Edges that cross are a 400.",
            "minItems": 3,
            "maxItems": 500
          },
          "azimuth_deg": {
            "type": "number",
            "description": "Direction wells are drilled, degrees clockwise from north.",
            "minimum": -360,
            "maximum": 360,
            "default": 0
          },
          "spacing_ft": {
            "type": "number",
            "description": "Distance between wells, ft.",
            "minimum": 100,
            "maximum": 10000
          },
          "lateral_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Lateral length, ft; null or absent runs each well edge to edge.",
            "minimum": 1000,
            "maximum": 30000
          },
          "setback_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Feet the wells keep from the unit's outline and holes, from every point of a well in any direction; with setback_end_ft, measured across the well (square to the azimuth).",
            "minimum": 0,
            "maximum": 2640,
            "default": 0
          },
          "area": {
            "$ref": "#/components/schemas/UnitArea",
            "description": "Instead of polygon: the unit as a GeoJSON Polygon or MultiPolygon in WGS 84, an area's geometry from POST /areas or what POST /units/summary takes. Holes are left out and each part is filled on its own; rings follow the unit scope's rules (POST /units/summary). Every edge costs work on every line, so a detailed outline may be too complex to fill: simplify it (as POST /areas' fill.polygon is)."
          },
          "setback_end_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Feet each well's heel and toe keep from the outline and holes, in a straight line; the rest of the well may pass closer as long as setback_ft holds across it. With lateral_length_ft, a piece whose heel or toe would fall closer is left out. Every edge gets both rules, whatever its angle.",
            "minimum": 0,
            "maximum": 2640
          },
          "min_lateral_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Shortest well, ft: every edge-to-edge chord at least this long is a well, instead of those within 95% of the longest. Not with lateral_length_ft.\n\nA kept chord longer than 30,000 ft between the rounded ends splits into the fewest equal wells of at most 30,000 ft, toe meeting heel; a split piece shorter than min_lateral_ft is left out, so such a chord may give no well.",
            "minimum": 1000,
            "maximum": 30000
          },
          "standoff_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Least distance from every lateral to the existing laterals (heel, else surface hole, to bottom hole) in its formation that lie in the unit or within standoff_ft of it, ft. Needs a formation for every bench.",
            "minimum": 0,
            "maximum": 5280
          },
          "wells_per_pad": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Groups the wells into pads of this many, numbered from 0 in each well's pad; a pad never spans two parts or tiers, so the last of each may hold fewer.\n\nA fill's pads only label wells: each well keeps its surface hole and the request's TIL date. To set a pad's values, post the fill's `wells` with `pads`. POST /plans keeps pad keys: with `layout`, the 1-based pad number as text; with `layouts`, the 1-based layout number, a hyphen, then the 1-based pad number. Without wells_per_pad, laid-out wells have no pad key. To price a pad, send its wells (a plan's layout echo `pads`) as a plan scenario's `wells` in POST /economics.",
            "minimum": 1,
            "maximum": 50
          },
          "benches": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A bench: spacing_ft or wells_per_section, not both, and the formation its wells land in.",
              "required": [
                "formation"
              ],
              "properties": {
                "spacing_ft": {
                  "type": "number",
                  "description": "Distance between the bench's wells, ft. Not with wells_per_section.",
                  "minimum": 100,
                  "maximum": 10000
                },
                "wells_per_section": {
                  "type": "number",
                  "description": "Instead of spacing_ft: wells per section, so spacing is 5,280 ft / wells_per_section (within spacing_ft's bounds).",
                  "minimum": 0.528,
                  "maximum": 52.8
                },
                "offset_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Shifts the bench's lines across the azimuth, ft (+ to the right looking along it), to stagger benches; 0, null or absent is no shift.\n\nLines pushed outside the area less setback_ft are dropped, not wrapped round, so a half-spacing stagger often holds one well fewer. A part with a non-zero offset isn't evened out, and in POST /plans' layouts no layout of the plan is, so a stagger set across layouts holds.",
                  "minimum": -10000,
                  "maximum": 10000,
                  "default": 0
                },
                "formation": {
                  "type": "string",
                  "description": "The bench's formation (case-insensitive): its wells land in it, and standoff_ft stands off its laterals."
                },
                "tvd_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 40000
                },
                "landing_below_top_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's `subsurface_sampling` (GET /model-sets).",
                  "exclusiveMinimum": -40000,
                  "exclusiveMaximum": 40000
                },
                "landing_fraction": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.\n\nThe top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.\n\nThe rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.\n\nTop and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.\n\nNeeds formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:\n\n- its formation has no grid there or no place in the column;\n- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);\n- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;\n- top and base averaged over the ends are under a foot apart: the zone pinches out.\n\nA well's inputs echo it when it was sent.",
                  "minimum": 0,
                  "maximum": 1
                },
                "fluid_bbl_per_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Fluid in bbl per lateral ft for the bench's wells: over the layout's, echoed as layer pad_formation. Needs one design, or none.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 1000
                },
                "proppant_lb_per_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Proppant in lb per lateral ft for the bench's wells, as fluid_bbl_per_ft is set.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 20000
                },
                "stage_length_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 2000
                },
                "clusters_per_stage": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 100
                },
                "frac_rate_bbl_per_min": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 500
                },
                "decline": {
                  "$ref": "#/components/schemas/DeclineSettings",
                  "description": "EUR settings for the bench's wells, as layer pad_formation; needs `eur` on.\n\nWith `eur` off, a `decline` on any layer is a 400, even `{}` or one that reaches no well, though either sets nothing. POST /exports `source` turns `eur` on when it is left out.\n\nEach field takes the narrowest value set: the well's; its pad's or layout's, `formations` entry or bench first; its scenario's, `formations` entry first; the request's `formations` entry; the request's `decline`; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's `b_max` beats a plan's `oil.b_max`. Once a value reaches a well, every well's `inputs.resolved.decline` gives each value and its layer, and the export's wells table adds them.\n\nA well whose `b_min` resolves at or above its `b_max` is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics `forecast` refuse a `decline`."
                }
              },
              "additionalProperties": false,
              "oneOf": [
                {
                  "required": [
                    "spacing_ft"
                  ],
                  "properties": {
                    "spacing_ft": true
                  }
                },
                {
                  "required": [
                    "wells_per_section"
                  ],
                  "properties": {
                    "wells_per_section": true
                  }
                }
              ]
            },
            "description": "Instead of spacing_ft: benches laid out together, each landed in its own formation, at its own tvd_ft, landing_below_top_ft or landing_fraction. Not with the layout's formation, tvd_ft, landing_below_top_ft or landing_fraction.",
            "minItems": 1,
            "maxItems": 10
          },
          "formation": {
            "type": "string",
            "description": "Target formation every laid-out well lands in (case-insensitive; GET /formations lists them). Required without benches; not with them."
          },
          "tvd_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 40000
          },
          "landing_below_top_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's `subsurface_sampling` (GET /model-sets).",
            "exclusiveMinimum": -40000,
            "exclusiveMaximum": 40000
          },
          "landing_fraction": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.\n\nThe top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.\n\nThe rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.\n\nTop and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.\n\nNeeds formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:\n\n- its formation has no grid there or no place in the column;\n- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);\n- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;\n- top and base averaged over the ends are under a foot apart: the zone pinches out.\n\nA well's inputs echo it when it was sent.",
            "minimum": 0,
            "maximum": 1
          },
          "til_date": {
            "type": "string",
            "description": "TIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.\n\nFrom GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.",
            "format": "date"
          },
          "fluid_bbl_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Fluid in bbl per lateral ft for the layout's wells: below a bench's and above a scenario's and the design's, echoed as layer pad. Works with `benches`. Needs one design, or none. A layout alone echoes no `til_date` or `landing` in `inputs.resolved`; completions here turn on its completion keys.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 1000
          },
          "proppant_lb_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Proppant in lb per lateral ft for the layout's wells, as fluid_bbl_per_ft is set.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 20000
          },
          "stage_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 2000
          },
          "clusters_per_stage": {
            "type": [
              "number",
              "null"
            ],
            "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 100
          },
          "frac_rate_bbl_per_min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 500
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings",
            "description": "EUR settings for the layout's wells, as layer pad; needs `eur` on.\n\nWith `eur` off, a `decline` on any layer is a 400, even `{}` or one that reaches no well, though either sets nothing. POST /exports `source` turns `eur` on when it is left out.\n\nEach field takes the narrowest value set: the well's; its pad's or layout's, `formations` entry or bench first; its scenario's, `formations` entry first; the request's `formations` entry; the request's `decline`; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's `b_max` beats a plan's `oil.b_max`. Once a value reaches a well, every well's `inputs.resolved.decline` gives each value and its layer, and the export's wells table adds them.\n\nA well whose `b_min` resolves at or above its `b_max` is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics `forecast` refuse a `decline`."
          }
        },
        "additionalProperties": false,
        "allOf": [
          {
            "oneOf": [
              {
                "required": [
                  "area"
                ],
                "properties": {
                  "area": true
                }
              },
              {
                "required": [
                  "polygon"
                ],
                "properties": {
                  "polygon": true
                }
              }
            ]
          },
          {
            "oneOf": [
              {
                "required": [
                  "spacing_ft",
                  "formation"
                ],
                "properties": {
                  "spacing_ft": true,
                  "formation": true
                },
                "not": {
                  "required": [
                    "benches"
                  ],
                  "properties": {
                    "benches": true
                  }
                }
              },
              {
                "required": [
                  "benches"
                ],
                "properties": {
                  "benches": true
                },
                "not": {
                  "anyOf": [
                    {
                      "required": [
                        "spacing_ft"
                      ],
                      "properties": {
                        "spacing_ft": true
                      }
                    },
                    {
                      "required": [
                        "formation"
                      ],
                      "properties": {
                        "formation": true
                      }
                    },
                    {
                      "required": [
                        "tvd_ft"
                      ],
                      "properties": {
                        "tvd_ft": true
                      }
                    },
                    {
                      "required": [
                        "landing_below_top_ft"
                      ],
                      "properties": {
                        "landing_below_top_ft": true
                      }
                    },
                    {
                      "required": [
                        "landing_fraction"
                      ],
                      "properties": {
                        "landing_fraction": true
                      }
                    }
                  ]
                }
              }
            ]
          }
        ]
      },
      "LayoutEcho": {
        "type": "object",
        "description": "What a layout laid out: POST /layouts/fill's answer without its wells, and the formation; with wells_per_pad or benches, pads and each bench's wells as well indexes.",
        "required": [
          "count",
          "azimuth_deg",
          "lateral_length_ft"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "Wells."
          },
          "azimuth_deg": {
            "type": "number",
            "description": "Azimuth used."
          },
          "spacing_ft": {
            "type": "number",
            "description": "Spacing used; left out with benches."
          },
          "lateral_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Length used, or null for edge to edge."
          },
          "setback_ft": {
            "type": "number",
            "description": "Setback used, ft; only when the request sent one."
          },
          "setback_end_ft": {
            "type": "number",
            "description": "End setback used, ft; only when sent."
          },
          "min_lateral_ft": {
            "type": "number",
            "description": "Shortest well used, ft; only when sent. No returned well is shorter: split pieces shorter than it are left out."
          },
          "standoff_ft": {
            "type": "number",
            "description": "Standoff used, ft; only when sent."
          },
          "standoff_wells": {
            "type": "integer",
            "description": "With standoff_ft: how many existing laterals POST /wells/search finds within standoff_ft of the unit (match lateral, in the wells' formations). The fill also clears laterals just past standoff_ft by that measure.",
            "minimum": 0
          },
          "wells_per_pad": {
            "type": "integer",
            "description": "Wells per pad; only when sent."
          },
          "wells_per_section": {
            "type": "number",
            "description": "With benches: their wells_per_section added up, the unit's total."
          },
          "pads": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "integer",
                "description": "A well index.",
                "minimum": 0
              },
              "description": "A pad's wells."
            },
            "description": "With wells_per_pad: each pad's wells, as indexes of the response's (or plan's) wells."
          },
          "benches": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A bench as laid out.",
              "required": [
                "spacing_ft",
                "wells_per_section",
                "offset_ft",
                "formation",
                "count",
                "wells"
              ],
              "properties": {
                "spacing_ft": {
                  "type": "number",
                  "description": "Spacing used, ft."
                },
                "wells_per_section": {
                  "type": "number",
                  "description": "5,280 ft / spacing_ft, or as sent."
                },
                "offset_ft": {
                  "type": "number",
                  "description": "Offset used, ft."
                },
                "formation": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The bench's formation, or null when none was sent."
                },
                "count": {
                  "type": "integer",
                  "description": "Wells in the bench.",
                  "minimum": 0
                },
                "wells": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "description": "A well index.",
                    "minimum": 0
                  },
                  "description": "The bench's wells, as indexes of the response's (or plan's) wells."
                }
              },
              "additionalProperties": false
            },
            "description": "With benches: each bench as laid out."
          },
          "formation": {
            "type": "string",
            "description": "The formation every well landed in, as GET /formations names it; left out with benches, which name their own."
          }
        },
        "additionalProperties": false
      },
      "PlanLayoutSource": {
        "type": "object",
        "description": "One of POST /plans' layouts: a LayoutSource, and its scenario.",
        "required": [],
        "properties": {
          "polygon": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LngLat"
            },
            "description": "Area corners, in order (closing point optional). Edges that cross are a 400.",
            "minItems": 3,
            "maxItems": 500
          },
          "azimuth_deg": {
            "type": "number",
            "description": "Direction wells are drilled, degrees clockwise from north.",
            "minimum": -360,
            "maximum": 360,
            "default": 0
          },
          "spacing_ft": {
            "type": "number",
            "description": "Distance between wells, ft.",
            "minimum": 100,
            "maximum": 10000
          },
          "lateral_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Lateral length, ft; null or absent runs each well edge to edge.",
            "minimum": 1000,
            "maximum": 30000
          },
          "setback_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Feet the wells keep from the unit's outline and holes, from every point of a well in any direction; with setback_end_ft, measured across the well (square to the azimuth).",
            "minimum": 0,
            "maximum": 2640,
            "default": 0
          },
          "area": {
            "$ref": "#/components/schemas/UnitArea",
            "description": "Instead of polygon: the unit as a GeoJSON Polygon or MultiPolygon in WGS 84, an area's geometry from POST /areas or what POST /units/summary takes. Holes are left out and each part is filled on its own; rings follow the unit scope's rules (POST /units/summary). Every edge costs work on every line, so a detailed outline may be too complex to fill: simplify it (as POST /areas' fill.polygon is)."
          },
          "setback_end_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Feet each well's heel and toe keep from the outline and holes, in a straight line; the rest of the well may pass closer as long as setback_ft holds across it. With lateral_length_ft, a piece whose heel or toe would fall closer is left out. Every edge gets both rules, whatever its angle.",
            "minimum": 0,
            "maximum": 2640
          },
          "min_lateral_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Shortest well, ft: every edge-to-edge chord at least this long is a well, instead of those within 95% of the longest. Not with lateral_length_ft.\n\nA kept chord longer than 30,000 ft between the rounded ends splits into the fewest equal wells of at most 30,000 ft, toe meeting heel; a split piece shorter than min_lateral_ft is left out, so such a chord may give no well.",
            "minimum": 1000,
            "maximum": 30000
          },
          "standoff_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Least distance from every lateral to the existing laterals (heel, else surface hole, to bottom hole) in its formation that lie in the unit or within standoff_ft of it, ft. Needs a formation for every bench.",
            "minimum": 0,
            "maximum": 5280
          },
          "wells_per_pad": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Groups the wells into pads of this many, numbered from 0 in each well's pad; a pad never spans two parts or tiers, so the last of each may hold fewer.\n\nA fill's pads only label wells: each well keeps its surface hole and the request's TIL date. To set a pad's values, post the fill's `wells` with `pads`. POST /plans keeps pad keys: with `layout`, the 1-based pad number as text; with `layouts`, the 1-based layout number, a hyphen, then the 1-based pad number. Without wells_per_pad, laid-out wells have no pad key. To price a pad, send its wells (a plan's layout echo `pads`) as a plan scenario's `wells` in POST /economics.",
            "minimum": 1,
            "maximum": 50
          },
          "benches": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A bench: spacing_ft or wells_per_section, not both, and the formation its wells land in.",
              "required": [
                "formation"
              ],
              "properties": {
                "spacing_ft": {
                  "type": "number",
                  "description": "Distance between the bench's wells, ft. Not with wells_per_section.",
                  "minimum": 100,
                  "maximum": 10000
                },
                "wells_per_section": {
                  "type": "number",
                  "description": "Instead of spacing_ft: wells per section, so spacing is 5,280 ft / wells_per_section (within spacing_ft's bounds).",
                  "minimum": 0.528,
                  "maximum": 52.8
                },
                "offset_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Shifts the bench's lines across the azimuth, ft (+ to the right looking along it), to stagger benches; 0, null or absent is no shift.\n\nLines pushed outside the area less setback_ft are dropped, not wrapped round, so a half-spacing stagger often holds one well fewer. A part with a non-zero offset isn't evened out, and in POST /plans' layouts no layout of the plan is, so a stagger set across layouts holds.",
                  "minimum": -10000,
                  "maximum": 10000,
                  "default": 0
                },
                "formation": {
                  "type": "string",
                  "description": "The bench's formation (case-insensitive): its wells land in it, and standoff_ft stands off its laterals."
                },
                "tvd_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 40000
                },
                "landing_below_top_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's `subsurface_sampling` (GET /model-sets).",
                  "exclusiveMinimum": -40000,
                  "exclusiveMaximum": 40000
                },
                "landing_fraction": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.\n\nThe top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.\n\nThe rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.\n\nTop and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.\n\nNeeds formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:\n\n- its formation has no grid there or no place in the column;\n- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);\n- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;\n- top and base averaged over the ends are under a foot apart: the zone pinches out.\n\nA well's inputs echo it when it was sent.",
                  "minimum": 0,
                  "maximum": 1
                },
                "fluid_bbl_per_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Fluid in bbl per lateral ft for the bench's wells: over the layout's, echoed as layer pad_formation. Needs one design, or none.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 1000
                },
                "proppant_lb_per_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Proppant in lb per lateral ft for the bench's wells, as fluid_bbl_per_ft is set.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 20000
                },
                "stage_length_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 2000
                },
                "clusters_per_stage": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 100
                },
                "frac_rate_bbl_per_min": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 500
                },
                "decline": {
                  "$ref": "#/components/schemas/DeclineSettings",
                  "description": "EUR settings for the bench's wells, as layer pad_formation; needs `eur` on.\n\nWith `eur` off, a `decline` on any layer is a 400, even `{}` or one that reaches no well, though either sets nothing. POST /exports `source` turns `eur` on when it is left out.\n\nEach field takes the narrowest value set: the well's; its pad's or layout's, `formations` entry or bench first; its scenario's, `formations` entry first; the request's `formations` entry; the request's `decline`; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's `b_max` beats a plan's `oil.b_max`. Once a value reaches a well, every well's `inputs.resolved.decline` gives each value and its layer, and the export's wells table adds them.\n\nA well whose `b_min` resolves at or above its `b_max` is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics `forecast` refuse a `decline`."
                }
              },
              "additionalProperties": false,
              "oneOf": [
                {
                  "required": [
                    "spacing_ft"
                  ],
                  "properties": {
                    "spacing_ft": true
                  }
                },
                {
                  "required": [
                    "wells_per_section"
                  ],
                  "properties": {
                    "wells_per_section": true
                  }
                }
              ]
            },
            "description": "Instead of spacing_ft: benches laid out together, each landed in its own formation, at its own tvd_ft, landing_below_top_ft or landing_fraction. Not with the layout's formation, tvd_ft, landing_below_top_ft or landing_fraction.",
            "minItems": 1,
            "maxItems": 10
          },
          "formation": {
            "type": "string",
            "description": "Target formation every laid-out well lands in (case-insensitive; GET /formations lists them). Required without benches; not with them."
          },
          "tvd_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 40000
          },
          "landing_below_top_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's `subsurface_sampling` (GET /model-sets).",
            "exclusiveMinimum": -40000,
            "exclusiveMaximum": 40000
          },
          "landing_fraction": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.\n\nThe top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.\n\nThe rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.\n\nTop and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.\n\nNeeds formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:\n\n- its formation has no grid there or no place in the column;\n- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);\n- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;\n- top and base averaged over the ends are under a foot apart: the zone pinches out.\n\nA well's inputs echo it when it was sent.",
            "minimum": 0,
            "maximum": 1
          },
          "til_date": {
            "type": "string",
            "description": "TIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.\n\nFrom GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.",
            "format": "date"
          },
          "fluid_bbl_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Fluid in bbl per lateral ft for the layout's wells: below a bench's and above a scenario's and the design's, echoed as layer pad. Works with `benches`. Needs one design, or none. A layout alone echoes no `til_date` or `landing` in `inputs.resolved`; completions here turn on its completion keys.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 1000
          },
          "proppant_lb_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Proppant in lb per lateral ft for the layout's wells, as fluid_bbl_per_ft is set.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 20000
          },
          "stage_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 2000
          },
          "clusters_per_stage": {
            "type": [
              "number",
              "null"
            ],
            "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 100
          },
          "frac_rate_bbl_per_min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 500
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings",
            "description": "EUR settings for the layout's wells, as layer pad; needs `eur` on.\n\nWith `eur` off, a `decline` on any layer is a 400, even `{}` or one that reaches no well, though either sets nothing. POST /exports `source` turns `eur` on when it is left out.\n\nEach field takes the narrowest value set: the well's; its pad's or layout's, `formations` entry or bench first; its scenario's, `formations` entry first; the request's `formations` entry; the request's `decline`; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's `b_max` beats a plan's `oil.b_max`. Once a value reaches a well, every well's `inputs.resolved.decline` gives each value and its layer, and the export's wells table adds them.\n\nA well whose `b_min` resolves at or above its `b_max` is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics `forecast` refuse a `decline`."
          },
          "scenario": {
            "type": "string",
            "description": "Every one of the layout's wells' scenario: send one on every layout, or on none. Layouts may share one, a development across units.",
            "minLength": 1,
            "maxLength": 60
          }
        },
        "additionalProperties": false,
        "allOf": [
          {
            "oneOf": [
              {
                "required": [
                  "area"
                ],
                "properties": {
                  "area": true
                }
              },
              {
                "required": [
                  "polygon"
                ],
                "properties": {
                  "polygon": true
                }
              }
            ]
          },
          {
            "oneOf": [
              {
                "required": [
                  "spacing_ft",
                  "formation"
                ],
                "properties": {
                  "spacing_ft": true,
                  "formation": true
                },
                "not": {
                  "required": [
                    "benches"
                  ],
                  "properties": {
                    "benches": true
                  }
                }
              },
              {
                "required": [
                  "benches"
                ],
                "properties": {
                  "benches": true
                },
                "not": {
                  "anyOf": [
                    {
                      "required": [
                        "spacing_ft"
                      ],
                      "properties": {
                        "spacing_ft": true
                      }
                    },
                    {
                      "required": [
                        "formation"
                      ],
                      "properties": {
                        "formation": true
                      }
                    },
                    {
                      "required": [
                        "tvd_ft"
                      ],
                      "properties": {
                        "tvd_ft": true
                      }
                    },
                    {
                      "required": [
                        "landing_below_top_ft"
                      ],
                      "properties": {
                        "landing_below_top_ft": true
                      }
                    },
                    {
                      "required": [
                        "landing_fraction"
                      ],
                      "properties": {
                        "landing_fraction": true
                      }
                    }
                  ]
                }
              }
            ]
          }
        ]
      },
      "ScenarioEcho": {
        "type": "object",
        "description": "A scenario of the request.",
        "required": [
          "name",
          "wells"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The scenario."
          },
          "wells": {
            "type": "integer",
            "description": "Its wells.",
            "minimum": 1
          },
          "pdp": {
            "type": "boolean",
            "description": "The scenario's own pdp; only when `scenarios` set one. Without it the scenario ran with the request's `pdp`."
          }
        },
        "additionalProperties": false
      },
      "ScenarioInput": {
        "type": "object",
        "description": "One scenario's values for its wells. tvd_ft, landing_below_top_ft and landing_fraction here are a 400: send them in formations.",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The scenario these values are for: exactly a name on the request's wells or layouts, trimmed, at most 60 characters, each once.",
            "minLength": 1,
            "maxLength": 60
          },
          "fluid_bbl_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Fluid in bbl per lateral ft for the scenario's wells: below a well's own, its pad's and a `formations` entry here, above the design's values. Needs one design, or none.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 1000
          },
          "proppant_lb_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Proppant in lb per lateral ft for the scenario's wells, as fluid_bbl_per_ft is set.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 20000
          },
          "stage_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 2000
          },
          "clusters_per_stage": {
            "type": [
              "number",
              "null"
            ],
            "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 100
          },
          "frac_rate_bbl_per_min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 500
          },
          "til_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "TIL date for the scenario's wells without their own or their pad's or layout's, over the request's til_date.\n\nTIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.\n\nFrom GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.",
            "format": "date"
          },
          "pdp": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether this scenario's wells space against existing (PDP) wells, over the request's `pdp`, so scenarios in one request can differ."
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings",
            "description": "EUR settings for the scenario's wells; needs `eur` on.\n\nWith `eur` off, a `decline` on any layer is a 400, even `{}` or one that reaches no well, though either sets nothing. POST /exports `source` turns `eur` on when it is left out.\n\nEach field takes the narrowest value set: the well's; its pad's or layout's, `formations` entry or bench first; its scenario's, `formations` entry first; the request's `formations` entry; the request's `decline`; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's `b_max` beats a plan's `oil.b_max`. Once a value reaches a well, every well's `inputs.resolved.decline` gives each value and its layer, and the export's wells table adds them.\n\nA well whose `b_min` resolves at or above its `b_max` is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics `forecast` refuse a `decline`."
          },
          "formations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScenarioFormationInput"
            },
            "description": "Values for the scenario's wells in one formation, each formation at most once. The only place a scenario sets landing.",
            "maxItems": 100
          }
        },
        "additionalProperties": false
      },
      "ScenarioFormationInput": {
        "type": "object",
        "description": "A scenario's or pad's values for its wells in one formation. Send one landing field at most.",
        "required": [
          "formation"
        ],
        "properties": {
          "formation": {
            "type": "string",
            "description": "Formation (case-insensitive; GET /formations lists them)."
          },
          "fluid_bbl_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Fluid in bbl per lateral ft for this formation's wells in the scenario or pad, over the entry's own. Needs one design, or none.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 1000
          },
          "proppant_lb_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Proppant in lb per lateral ft, as fluid_bbl_per_ft is set.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 20000
          },
          "stage_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 2000
          },
          "clusters_per_stage": {
            "type": [
              "number",
              "null"
            ],
            "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 100
          },
          "frac_rate_bbl_per_min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 500
          },
          "tvd_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "True vertical depth in ft. Landing falls through as one unit: a well, or a narrower layer, that sets any of tvd_ft, landing_below_top_ft or landing_fraction keeps its own, so this reaches only wells that set none.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 40000
          },
          "landing_below_top_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft: ft below the formation top, as on a well.",
            "exclusiveMinimum": -40000,
            "exclusiveMaximum": 40000
          },
          "landing_fraction": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft or landing_below_top_ft: 0 at the formation top to 1 at its base, as on a well.",
            "minimum": 0,
            "maximum": 1
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings",
            "description": "EUR settings for this formation's wells in the scenario or pad; needs `eur` on.\n\nWith `eur` off, a `decline` on any layer is a 400, even `{}` or one that reaches no well, though either sets nothing. POST /exports `source` turns `eur` on when it is left out.\n\nEach field takes the narrowest value set: the well's; its pad's or layout's, `formations` entry or bench first; its scenario's, `formations` entry first; the request's `formations` entry; the request's `decline`; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's `b_max` beats a plan's `oil.b_max`. Once a value reaches a well, every well's `inputs.resolved.decline` gives each value and its layer, and the export's wells table adds them.\n\nA well whose `b_min` resolves at or above its `b_max` is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics `forecast` refuse a `decline`."
          }
        },
        "additionalProperties": false
      },
      "PadInput": {
        "type": "object",
        "description": "One pad's values for its wells. A pad has no `pdp`: the field is a 400.",
        "required": [
          "pad"
        ],
        "properties": {
          "pad": {
            "type": [
              "integer",
              "string"
            ],
            "minLength": 1,
            "maxLength": 60,
            "description": "The pad these values are for: an integer or text as the wells name it, trimmed, at most 60 characters, each once; 1 and \"1\" are one pad."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The pad's name, 1 to 60 characters once trimmed; null is none, and a blank name is a 400. Names needn't be unique: the key still groups and orders pads, pairs them in comparisons and filters with `pad=`.\n\nPOST /plans keeps it: the economics export's `pad` column writes it instead of the key on well and pad rows, GET /plans/{id}/stats?group_by=pad gives it as `groups[].name`, GET /plans/{id}/rollup as `pads[].name`, and the type curve, plan economics and comparisons by pad give it beside the key. POST /forecasts and POST /exports `source` check it but don't use it.",
            "maxLength": 60
          },
          "fluid_bbl_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Fluid in bbl per lateral ft for the pad's wells: below a well's own and a `formations` entry here, above a scenario's and the design's. Needs one design, or none.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 1000
          },
          "proppant_lb_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Proppant in lb per lateral ft for the pad's wells, as fluid_bbl_per_ft is set.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 20000
          },
          "stage_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 2000
          },
          "clusters_per_stage": {
            "type": [
              "number",
              "null"
            ],
            "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 100
          },
          "frac_rate_bbl_per_min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 500
          },
          "til_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "TIL date for the pad's wells without their own, over a scenario's and the request's til_date.\n\nTIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.\n\nFrom GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.",
            "format": "date"
          },
          "tvd_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "True vertical depth in ft for the pad's wells. Landing falls through as one unit, so a well, or a `formations` entry here, that sets any landing field keeps it.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 40000
          },
          "landing_below_top_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft: ft below the top of each well's own formation; a well that takes it needs one.",
            "exclusiveMinimum": -40000,
            "exclusiveMaximum": 40000
          },
          "landing_fraction": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft or landing_below_top_ft: 0 at the top of each well's own formation to 1 at its base; a well that takes it needs one.",
            "minimum": 0,
            "maximum": 1
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings",
            "description": "EUR settings for the pad's wells; needs `eur` on.\n\nWith `eur` off, a `decline` on any layer is a 400, even `{}` or one that reaches no well, though either sets nothing. POST /exports `source` turns `eur` on when it is left out.\n\nEach field takes the narrowest value set: the well's; its pad's or layout's, `formations` entry or bench first; its scenario's, `formations` entry first; the request's `formations` entry; the request's `decline`; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's `b_max` beats a plan's `oil.b_max`. Once a value reaches a well, every well's `inputs.resolved.decline` gives each value and its layer, and the export's wells table adds them.\n\nA well whose `b_min` resolves at or above its `b_max` is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics `forecast` refuse a `decline`."
          },
          "formations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScenarioFormationInput"
            },
            "description": "Values for the pad's wells in one formation, each formation at most once.",
            "maxItems": 100
          }
        },
        "additionalProperties": false
      },
      "FormationLandingInput": {
        "type": "object",
        "description": "The request's landing and EUR settings in one formation. Send one landing field at most.",
        "required": [
          "formation"
        ],
        "properties": {
          "formation": {
            "type": "string",
            "description": "Formation (case-insensitive; GET /formations lists them)."
          },
          "tvd_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "True vertical depth in ft for the request's wells in this formation that no narrower layer lands.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 40000
          },
          "landing_below_top_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft: ft below the formation top, as on a well.",
            "exclusiveMinimum": -40000,
            "exclusiveMaximum": 40000
          },
          "landing_fraction": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft or landing_below_top_ft: 0 at the formation top to 1 at its base, as on a well.",
            "minimum": 0,
            "maximum": 1
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings",
            "description": "EUR settings for the request's wells in this formation; needs `eur` on.\n\nWith `eur` off, a `decline` on any layer is a 400, even `{}` or one that reaches no well, though either sets nothing. POST /exports `source` turns `eur` on when it is left out.\n\nEach field takes the narrowest value set: the well's; its pad's or layout's, `formations` entry or bench first; its scenario's, `formations` entry first; the request's `formations` entry; the request's `decline`; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's `b_max` beats a plan's `oil.b_max`. Once a value reaches a well, every well's `inputs.resolved.decline` gives each value and its layer, and the export's wells table adds them.\n\nA well whose `b_min` resolves at or above its `b_max` is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics `forecast` refuse a `decline`."
          }
        },
        "additionalProperties": false
      },
      "PlanLayoutEcho": {
        "type": "object",
        "description": "One of a plan's layouts as laid out: a LayoutEcho with its first well's plan index; pads and benches index the plan's wells.",
        "required": [
          "first",
          "count",
          "azimuth_deg",
          "lateral_length_ft"
        ],
        "properties": {
          "first": {
            "type": "integer",
            "description": "The plan index of the layout's first well; its wells follow in order.",
            "minimum": 0
          },
          "scenario": {
            "type": "string",
            "description": "When the layout was sent with one: its scenario."
          },
          "count": {
            "type": "integer",
            "description": "Wells."
          },
          "azimuth_deg": {
            "type": "number",
            "description": "Azimuth used."
          },
          "spacing_ft": {
            "type": "number",
            "description": "Spacing used; left out with benches."
          },
          "lateral_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Length used, or null for edge to edge."
          },
          "setback_ft": {
            "type": "number",
            "description": "Setback used, ft; only when the request sent one."
          },
          "setback_end_ft": {
            "type": "number",
            "description": "End setback used, ft; only when sent."
          },
          "min_lateral_ft": {
            "type": "number",
            "description": "Shortest well used, ft; only when sent. No returned well is shorter: split pieces shorter than it are left out."
          },
          "standoff_ft": {
            "type": "number",
            "description": "Standoff used, ft; only when sent."
          },
          "standoff_wells": {
            "type": "integer",
            "description": "With standoff_ft: how many existing laterals POST /wells/search finds within standoff_ft of the unit (match lateral, in the wells' formations). The fill also clears laterals just past standoff_ft by that measure.",
            "minimum": 0
          },
          "wells_per_pad": {
            "type": "integer",
            "description": "Wells per pad; only when sent."
          },
          "wells_per_section": {
            "type": "number",
            "description": "With benches: their wells_per_section added up, the unit's total."
          },
          "pads": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "integer",
                "description": "A well index.",
                "minimum": 0
              },
              "description": "A pad's wells."
            },
            "description": "With wells_per_pad: each pad's wells, as indexes of the response's (or plan's) wells."
          },
          "benches": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A bench as laid out.",
              "required": [
                "spacing_ft",
                "wells_per_section",
                "offset_ft",
                "formation",
                "count",
                "wells"
              ],
              "properties": {
                "spacing_ft": {
                  "type": "number",
                  "description": "Spacing used, ft."
                },
                "wells_per_section": {
                  "type": "number",
                  "description": "5,280 ft / spacing_ft, or as sent."
                },
                "offset_ft": {
                  "type": "number",
                  "description": "Offset used, ft."
                },
                "formation": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The bench's formation, or null when none was sent."
                },
                "count": {
                  "type": "integer",
                  "description": "Wells in the bench.",
                  "minimum": 0
                },
                "wells": {
                  "type": "array",
                  "items": {
                    "type": "integer",
                    "description": "A well index.",
                    "minimum": 0
                  },
                  "description": "The bench's wells, as indexes of the response's (or plan's) wells."
                }
              },
              "additionalProperties": false
            },
            "description": "With benches: each bench as laid out."
          },
          "formation": {
            "type": "string",
            "description": "The formation every well landed in, as GET /formations names it; left out with benches, which name their own."
          }
        },
        "additionalProperties": false
      },
      "WellInput": {
        "type": "object",
        "description": "A drawn well. A blank TVD is estimated; completions come from the request's designs, unless the well sets its own.",
        "required": [
          "shl",
          "bhl"
        ],
        "properties": {
          "shl": {
            "type": "array",
            "description": "Surface hole location, [lng, lat].",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "bhl": {
            "type": "array",
            "description": "Bottom hole (toe) location, [lng, lat]. The lateral runs from heel, else shl, to bhl and must be 100 to 50,000 ft long.",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Target formation (case-insensitive; GET /formations lists them). Needed to forecast and to estimate TVD."
          },
          "tvd_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 40000
          },
          "landing_below_top_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's `subsurface_sampling` (GET /model-sets).",
            "exclusiveMinimum": -40000,
            "exclusiveMaximum": 40000
          },
          "heel": {
            "type": [
              "array",
              "null"
            ],
            "description": "Where the lateral starts, [lng, lat], when not at `shl`, the surface hole; absent or null, it starts at `shl`. `shl` must be within 50,000 ft of it.\n\nWith it, the lateral length and its 100 to 50,000 ft check, spacing, gun barrel laterals, PDP wells and model analogs run from heel to bhl. Subsurface grids still sample at `shl` and `bhl` as the set's `subsurface_sampling` says, and structure tops, landing, TVD estimates, the KB elevation and the model's surface hole inputs stay at `shl`.",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "typed_lateral": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TypedLateral"
              },
              {
                "type": "null"
              }
            ],
            "description": "A lateral length typed for the well, as an inventory file gives it: `length_ft`, and the `heel` (the well's heel, else its `shl`) and `bhl` it was typed for.\n\nThe model gets `length_ft` as `novi_lateral_length`, and spacing, the completion totals, analogs, normalize_lateral_ft and pricing use it, while the well's heel (else shl) and bhl equal those two exactly and it is within 5% of the length measured between them or within 100 to 50,000 ft; otherwise the measured length. A client that moves an end can send it unchanged: the well then uses the measured length.\n\nReads give the length used as `lateral_length_ft`, with `lateral_length_source`. Optional: absent or null, the measured length.\n\nPOST /inventories/read sets it from a file's stated length unless that is both more than 5% off the drawn one and outside 100 to 50,000 ft, with an issue when it is more than 5% off."
          },
          "lateral_outside": {
            "type": [
              "string",
              "null"
            ],
            "description": "Ignored; accepted so POST /layouts/fill wells with lateral_check can be sent as they are.",
            "enum": [
              "above",
              "below",
              null
            ]
          },
          "landing_fraction": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.\n\nThe top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.\n\nThe rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.\n\nTop and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.\n\nNeeds formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:\n\n- its formation has no grid there or no place in the column;\n- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);\n- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;\n- top and base averaged over the ends are under a foot apart: the zone pinches out.\n\nA well's inputs echo it when it was sent.",
            "minimum": 0,
            "maximum": 1
          },
          "lateral_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Ignored: the lateral runs from heel, else shl, to bhl, unless `typed_lateral` applies. Accepted so POST /layouts/fill wells can be sent as they are."
          },
          "til_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "TIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.\n\nFrom GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.",
            "format": "date"
          },
          "part": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Ignored, as is bench: accepted so POST /layouts/fill wells can be sent as they are."
          },
          "bench": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Ignored."
          },
          "pad": {
            "type": [
              "number",
              "string",
              "null"
            ],
            "description": "The pad the well is on: a whole number, as POST /layouts/fill numbers them, or text of 1 to 60 characters, trimmed; 1 and \"1\" are one pad.\n\nPOST /plans keeps a valid key whenever sent, for `group_by=pad` and the `pad=` filter, and doesn't echo it on wells; other requests read it only with `pads`. It is checked (a 400 on a bad value) only with `pads`; without `pads`, a value that isn't a pad is ignored."
          },
          "scenario": {
            "type": "string",
            "description": "The alternative the well is in: a scenario's wells space against only each other and existing wells, never another scenario's. A name of 1 to 60 characters, trimmed.\n\nEqual names (exact, case-sensitive) are one scenario; with pdp false its wells space against only each other. Give every well a scenario, or none (400 at the first without one). At most 10 scenarios on POST /forecasts, each its own spacing run, and 20 on POST /plans (400 at the first well past it, with details.max and details.count). Designs and pdp apply to every scenario unless `scenarios` sets its own.",
            "minLength": 1,
            "maxLength": 60
          },
          "fluid_bbl_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "This well's fluid in bbl per lateral ft.\n\nEach field takes the narrowest layer that sets it, on its own: the well, its pad's entry in `pads` or its layout (the bench or formation entry, then overall), its entry in `scenarios` (formation entry, then overall), the design's `formations` entry for its formation, the design, then the default: the recent-completions median of the well's formation, else the play's.\n\nNeeds one design or none; with more, the request is a 400 naming the well. POST /gun-barrels refuses it. Sending one adds `resolved` to every well's `inputs` in the request.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 1000
          },
          "proppant_lb_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "This well's proppant in lb per lateral ft.\n\nEach field takes the narrowest layer that sets it, on its own: the well, its pad's entry in `pads` or its layout (the bench or formation entry, then overall), its entry in `scenarios` (formation entry, then overall), the design's `formations` entry for its formation, the design, then the default: the recent-completions median of the well's formation, else the play's.\n\nNeeds one design or none; with more, the request is a 400 naming the well. POST /gun-barrels refuses it. Sending one adds `resolved` to every well's `inputs` in the request.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 20000
          },
          "stage_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 2000
          },
          "clusters_per_stage": {
            "type": [
              "number",
              "null"
            ],
            "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 100
          },
          "frac_rate_bbl_per_min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 500
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings",
            "description": "EUR settings for this well; needs `eur` on.\n\nWith `eur` off, a `decline` on any layer is a 400, even `{}` or one that reaches no well, though either sets nothing. POST /exports `source` turns `eur` on when it is left out.\n\nEach field takes the narrowest value set: the well's; its pad's or layout's, `formations` entry or bench first; its scenario's, `formations` entry first; the request's `formations` entry; the request's `decline`; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's `b_max` beats a plan's `oil.b_max`. Once a value reaches a well, every well's `inputs.resolved.decline` gives each value and its layer, and the export's wells table adds them.\n\nA well whose `b_min` resolves at or above its `b_max` is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics `forecast` refuse a `decline`."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your name for the well, 1 to 60 characters once trimmed, on POST /plans, POST /forecasts and POST /inventories/write; other routes that take wells answer 400. null is none; a blank name is a 400.\n\nNames needn't be unique. Reads show it beside `label`, which stays Plan well N (Drawn well N on POST /forecasts). A plan's export tables put it in their `well` column, keeping their row order, with a leading quote where a spreadsheet would read it as a formula. ARIES heads the well with it, unquoted, and sorts by header, so wells with one name share a header: send `aries.well_key: id` to keep them apart.",
            "maxLength": 60
          }
        },
        "additionalProperties": false
      },
      "WellInputEcho": {
        "type": "object",
        "description": "The well as requested, blanks as null. tvd_ft, landing_below_top_ft, landing_fraction and til_date show a layer's value when the well took one.",
        "required": [
          "shl",
          "bhl",
          "formation",
          "tvd_ft",
          "landing_below_top_ft"
        ],
        "properties": {
          "shl": {
            "type": "array",
            "description": "Surface hole location, [lng, lat].",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "bhl": {
            "type": "array",
            "description": "Bottom hole (toe) location, [lng, lat]. The lateral runs from heel, else shl, to bhl and must be 100 to 50,000 ft long.",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Target formation (case-insensitive; GET /formations lists them). Needed to forecast and to estimate TVD."
          },
          "tvd_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 40000
          },
          "landing_below_top_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's `subsurface_sampling` (GET /model-sets).",
            "exclusiveMinimum": -40000,
            "exclusiveMaximum": 40000
          },
          "heel": {
            "type": "array",
            "description": "The heel sent; only when the request sent one.",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "typed_lateral": {
            "$ref": "#/components/schemas/TypedLateral",
            "description": "The typed_lateral sent; only when the request sent one."
          },
          "landing_fraction": {
            "type": "number",
            "description": "The landing_fraction sent; only when the request sent one.",
            "minimum": 0,
            "maximum": 1
          },
          "til_date": {
            "type": "string",
            "description": "The TIL date the well ran with: its own, else its pad's or layout's, else its scenario's, else the request's til_date. Only when the request sent a date for it; otherwise the well was TIL today.",
            "format": "date"
          },
          "scenario": {
            "type": "string",
            "description": "The well's scenario, only when the request sent scenarios."
          },
          "fluid_bbl_per_ft": {
            "type": "number",
            "description": "The well's own fluid sent, bbl/ft; only when the request sent one."
          },
          "proppant_lb_per_ft": {
            "type": "number",
            "description": "The well's own proppant sent, lb/ft; only when the request sent one."
          },
          "stage_length_ft": {
            "type": "number",
            "description": "The well's own stage_length_ft sent; only when the request sent one and the set's models read it."
          },
          "clusters_per_stage": {
            "type": "number",
            "description": "The well's own clusters_per_stage sent; only when the request sent one and the set's models read it."
          },
          "frac_rate_bbl_per_min": {
            "type": "number",
            "description": "The well's own frac_rate_bbl_per_min sent; only when the request sent one and the set's models read it."
          },
          "resolved": {
            "$ref": "#/components/schemas/ResolvedInputs"
          }
        },
        "additionalProperties": false
      },
      "TypedLateral": {
        "type": "object",
        "description": "A lateral length typed for a well and the ends it was typed for.",
        "required": [
          "length_ft",
          "heel",
          "bhl"
        ],
        "properties": {
          "length_ft": {
            "type": "number",
            "description": "The typed length, ft.",
            "minimum": 0,
            "maximum": 1000000
          },
          "heel": {
            "type": "array",
            "description": "Where the lateral started when the length was typed: the well's heel, else its shl, [lng, lat].",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "bhl": {
            "type": "array",
            "description": "The bottom hole the length was typed for, [lng, lat].",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          }
        },
        "additionalProperties": false
      },
      "ResolvedValue": {
        "type": "object",
        "description": "A value and the layer it came from.",
        "required": [
          "value",
          "layer"
        ],
        "properties": {
          "value": {
            "type": "number",
            "description": "The value the well was forecast with."
          },
          "layer": {
            "type": "string",
            "description": "The narrowest layer that set the value. A value an assumption set filled reads as the field it filled (plan or plan_formation), and the plan's `assumption_set.filled` lists those fields.\n\n- well: the well.\n- pad_formation: its pad's `formations` entry for its formation, or its layout bench.\n- pad: its `pads` entry, or its layout.\n- scenario_formation: its scenario's `formations` entry for its formation.\n- scenario: its `scenarios` entry.\n- plan_formation: the design's entry for its formation, or for a landing the request's `formations` entry.\n- plan: the design, or the request's til_date.\n- default: nothing set it.",
            "enum": [
              "well",
              "pad_formation",
              "pad",
              "scenario_formation",
              "scenario",
              "plan_formation",
              "plan",
              "default"
            ]
          }
        },
        "additionalProperties": false
      },
      "ResolvedDate": {
        "type": "object",
        "description": "A TIL date and the layer it came from.",
        "required": [
          "layer"
        ],
        "properties": {
          "value": {
            "type": "string",
            "description": "The TIL date the well ran with; left out when no layer set one, and the well ran on the plan's start day, or today in POST /forecasts.",
            "format": "date"
          },
          "layer": {
            "type": "string",
            "description": "The narrowest layer that set the value. A value an assumption set filled reads as the field it filled (plan or plan_formation), and the plan's `assumption_set.filled` lists those fields.\n\n- well: the well.\n- pad_formation: its pad's `formations` entry for its formation, or its layout bench.\n- pad: its `pads` entry, or its layout.\n- scenario_formation: its scenario's `formations` entry for its formation.\n- scenario: its `scenarios` entry.\n- plan_formation: the design's entry for its formation, or for a landing the request's `formations` entry.\n- plan: the design, or the request's til_date.\n- default: nothing set it.",
            "enum": [
              "well",
              "pad_formation",
              "pad",
              "scenario_formation",
              "scenario",
              "plan_formation",
              "plan",
              "default"
            ]
          }
        },
        "additionalProperties": false
      },
      "ResolvedLanding": {
        "type": "object",
        "description": "The landing a layer set, and which: one of the three, or none with layer default, when TVD was estimated. `estimates.tvd_ft` is the TVD the well ran at.",
        "required": [
          "layer"
        ],
        "properties": {
          "tvd_ft": {
            "type": "number",
            "description": "The TVD set, ft."
          },
          "landing_below_top_ft": {
            "type": "number",
            "description": "The landing below the formation top set, ft."
          },
          "landing_fraction": {
            "type": "number",
            "description": "The fraction of the formation's thickness set."
          },
          "layer": {
            "type": "string",
            "description": "The narrowest layer that set the value. A value an assumption set filled reads as the field it filled (plan or plan_formation), and the plan's `assumption_set.filled` lists those fields.\n\n- well: the well.\n- pad_formation: its pad's `formations` entry for its formation, or its layout bench.\n- pad: its `pads` entry, or its layout.\n- scenario_formation: its scenario's `formations` entry for its formation.\n- scenario: its `scenarios` entry.\n- plan_formation: the design's entry for its formation, or for a landing the request's `formations` entry.\n- plan: the design, or the request's til_date.\n- default: nothing set it.",
            "enum": [
              "well",
              "pad_formation",
              "pad",
              "scenario_formation",
              "scenario",
              "plan_formation",
              "plan",
              "default"
            ]
          }
        },
        "additionalProperties": false
      },
      "ResolvedStreamDecline": {
        "type": "object",
        "description": "What one stream was fit with, each value with its layer.",
        "required": [
          "terminal_decline",
          "b_min",
          "b_max"
        ],
        "properties": {
          "terminal_decline": {
            "$ref": "#/components/schemas/ResolvedValue",
            "description": "Terminal decline, as a fraction per year."
          },
          "b_min": {
            "$ref": "#/components/schemas/ResolvedValue",
            "description": "Lowest b."
          },
          "b_max": {
            "$ref": "#/components/schemas/ResolvedValue",
            "description": "Highest b."
          }
        },
        "additionalProperties": false
      },
      "ResolvedDecline": {
        "type": "object",
        "description": "The EUR settings this well was fit with, each value with the layer that set it.\n\nOn every well once a well, pad, layout or bench, scenario or `formations` entry of the request sets one; a plan with no layer below it has no `resolved.decline`, and its `decline` echo's flat fields are the base. A stream's value beats its layer's base, and the narrower layer wins first: a well's `b_max` beats a plan's `oil.b_max`.",
        "required": [
          "eur_years",
          "oil",
          "gas"
        ],
        "properties": {
          "eur_years": {
            "$ref": "#/components/schemas/ResolvedValue",
            "description": "Years to EUR, every stream's."
          },
          "oil": {
            "$ref": "#/components/schemas/ResolvedStreamDecline"
          },
          "gas": {
            "$ref": "#/components/schemas/ResolvedStreamDecline"
          },
          "water": {
            "$ref": "#/components/schemas/ResolvedStreamDecline",
            "description": "Only with eur_water: true."
          },
          "base": {
            "$ref": "#/components/schemas/ResolvedStreamDecline",
            "description": "Only with include=decline_base on GET /plans/{id} or GET /plans/{id}/wells/{index}: the flat terminal_decline, b_min and b_max this well ran with, which a stream's value goes over. Left out on older plans.\n\n- Each `layer` is the narrowest layer whose flat field set it (`plan` for the request's flat `decline`), else `default`. A value sent on a stream names its layer only on that stream (`oil`, `gas`), so compare them to tell the two apart.\n- The depletion chain's water extension reads these settings.\n- Rebuild a plan's own `decline` from its `decline` echo, without `per_well`, not from the `plan` values here: a plan field every well beats isn't here, and the request's flat pair and each stream's are checked on their own."
          }
        },
        "additionalProperties": false
      },
      "ResolvedInputs": {
        "type": "object",
        "description": "What this well was forecast with: its completions once a well, pad, layout or scenario of the request sets one, its TIL date and landing once a pad, scenario or `formations` entry sets one that a well takes (a layout alone doesn't), and then on every well. Read each key as optional: a later release may send some of these and add others.",
        "required": [],
        "properties": {
          "fluid_bbl_per_ft": {
            "$ref": "#/components/schemas/ResolvedValue",
            "description": "Fluid used, bbl/ft."
          },
          "proppant_lb_per_ft": {
            "$ref": "#/components/schemas/ResolvedValue",
            "description": "Proppant used, lb/ft."
          },
          "stage_length_ft": {
            "$ref": "#/components/schemas/ResolvedValue",
            "description": "The stage_length_ft used, on a model set whose models read it."
          },
          "clusters_per_stage": {
            "$ref": "#/components/schemas/ResolvedValue",
            "description": "The clusters_per_stage used, on a model set whose models read it."
          },
          "frac_rate_bbl_per_min": {
            "$ref": "#/components/schemas/ResolvedValue",
            "description": "The frac_rate_bbl_per_min used, on a model set whose models read it."
          },
          "completions_source": {
            "type": "string",
            "description": "input when a request set both, else how the default was found."
          },
          "til_date": {
            "$ref": "#/components/schemas/ResolvedDate"
          },
          "landing": {
            "$ref": "#/components/schemas/ResolvedLanding"
          },
          "decline": {
            "$ref": "#/components/schemas/ResolvedDecline"
          }
        },
        "additionalProperties": false
      },
      "DesignEstimates": {
        "type": "object",
        "description": "The TVD the models used, entered or estimated.",
        "required": [
          "tvd_ft",
          "tvd_source"
        ],
        "properties": {
          "tvd_ft": {
            "type": "number",
            "description": "TVD used, ft."
          },
          "tvd_source": {
            "type": "string",
            "description": "input, or how it was estimated."
          }
        },
        "additionalProperties": false
      },
      "DesignInput": {
        "type": "object",
        "description": "A completion design. Blank values are estimated.",
        "required": [],
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your name for the design; defaults to Design 1, Design 2, ….",
            "maxLength": 60
          },
          "fluid_bbl_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 1000
          },
          "proppant_lb_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 20000
          },
          "stage_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 2000
          },
          "clusters_per_stage": {
            "type": [
              "number",
              "null"
            ],
            "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 100
          },
          "frac_rate_bbl_per_min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 500
          },
          "formations": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "Completions for one formation's wells; blanks fall back to the design's values, then that formation's median.",
              "required": [
                "formation"
              ],
              "properties": {
                "formation": {
                  "type": "string",
                  "description": "Formation (case-insensitive)."
                },
                "fluid_bbl_per_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 1000
                },
                "proppant_lb_per_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 20000
                },
                "stage_length_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 2000
                },
                "clusters_per_stage": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 100
                },
                "frac_rate_bbl_per_min": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                  "exclusiveMinimum": 0,
                  "exclusiveMaximum": 500
                }
              },
              "additionalProperties": false
            },
            "description": "Per-formation overrides, each formation at most once."
          }
        },
        "additionalProperties": false
      },
      "Design": {
        "type": "object",
        "description": "A completion design as run.",
        "required": [
          "index",
          "name",
          "inputs",
          "fluid_bbl_per_ft",
          "proppant_lb_per_ft",
          "completions_source",
          "formations"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "Position in designs.",
            "minimum": 0
          },
          "name": {
            "type": "string",
            "description": "Name."
          },
          "inputs": {
            "type": "object",
            "description": "As requested, blanks as null; the stage fields only where the set's models read them.",
            "required": [
              "fluid_bbl_per_ft",
              "proppant_lb_per_ft"
            ],
            "properties": {
              "fluid_bbl_per_ft": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.",
                "exclusiveMinimum": 0,
                "exclusiveMaximum": 1000
              },
              "proppant_lb_per_ft": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.",
                "exclusiveMinimum": 0,
                "exclusiveMaximum": 20000
              },
              "stage_length_ft": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                "exclusiveMinimum": 0,
                "exclusiveMaximum": 2000
              },
              "clusters_per_stage": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                "exclusiveMinimum": 0,
                "exclusiveMaximum": 100
              },
              "frac_rate_bbl_per_min": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                "exclusiveMinimum": 0,
                "exclusiveMaximum": 500
              }
            },
            "additionalProperties": false
          },
          "fluid_bbl_per_ft": {
            "type": "number",
            "description": "Fluid used, bbl/ft."
          },
          "proppant_lb_per_ft": {
            "type": "number",
            "description": "Proppant used, lb/ft."
          },
          "stage_length_ft": {
            "type": "number",
            "description": "Stage length used, ft: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median."
          },
          "clusters_per_stage": {
            "type": "number",
            "description": "Clusters per stage used: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median."
          },
          "frac_rate_bbl_per_min": {
            "type": "number",
            "description": "Frac rate used, bbl/min: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median."
          },
          "completions_source": {
            "type": "string",
            "description": "input when both were entered, otherwise how the defaults were made."
          },
          "sources": {
            "type": "object",
            "description": "How each stage value used was found: input when the request set it, else the median's text.",
            "required": [],
            "properties": {
              "stage_length_ft": {
                "type": "string",
                "description": "input, or how the default was made."
              },
              "clusters_per_stage": {
                "type": "string",
                "description": "input, or how the default was made."
              },
              "frac_rate_bbl_per_min": {
                "type": "string",
                "description": "input, or how the default was made."
              }
            },
            "additionalProperties": false
          },
          "formations": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "What one formation's wells were forecast with.",
              "required": [
                "formation",
                "inputs",
                "fluid_bbl_per_ft",
                "proppant_lb_per_ft",
                "completions_source"
              ],
              "properties": {
                "formation": {
                  "type": "string",
                  "description": "Formation."
                },
                "inputs": {
                  "type": "object",
                  "description": "As requested, blanks as null; the stage fields only where the set's models read them.",
                  "required": [
                    "fluid_bbl_per_ft",
                    "proppant_lb_per_ft"
                  ],
                  "properties": {
                    "fluid_bbl_per_ft": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.",
                      "exclusiveMinimum": 0,
                      "exclusiveMaximum": 1000
                    },
                    "proppant_lb_per_ft": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.",
                      "exclusiveMinimum": 0,
                      "exclusiveMaximum": 20000
                    },
                    "stage_length_ft": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                      "exclusiveMinimum": 0,
                      "exclusiveMaximum": 2000
                    },
                    "clusters_per_stage": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                      "exclusiveMinimum": 0,
                      "exclusiveMaximum": 100
                    },
                    "frac_rate_bbl_per_min": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
                      "exclusiveMinimum": 0,
                      "exclusiveMaximum": 500
                    }
                  },
                  "additionalProperties": false
                },
                "fluid_bbl_per_ft": {
                  "type": "number",
                  "description": "Fluid used, bbl/ft."
                },
                "proppant_lb_per_ft": {
                  "type": "number",
                  "description": "Proppant used, lb/ft."
                },
                "stage_length_ft": {
                  "type": "number",
                  "description": "Stage length used, ft: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median."
                },
                "clusters_per_stage": {
                  "type": "number",
                  "description": "Clusters per stage used: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median."
                },
                "frac_rate_bbl_per_min": {
                  "type": "number",
                  "description": "Frac rate used, bbl/min: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median."
                },
                "completions_source": {
                  "type": "string",
                  "description": "input when both were entered, otherwise how the defaults were made."
                },
                "sources": {
                  "type": "object",
                  "description": "How each stage value used was found: input when the request set it, else the median's text.",
                  "required": [],
                  "properties": {
                    "stage_length_ft": {
                      "type": "string",
                      "description": "input, or how the default was made."
                    },
                    "clusters_per_stage": {
                      "type": "string",
                      "description": "input, or how the default was made."
                    },
                    "frac_rate_bbl_per_min": {
                      "type": "string",
                      "description": "input, or how the default was made."
                    }
                  },
                  "additionalProperties": false
                }
              },
              "additionalProperties": false
            },
            "description": "Every formation the request's wells or the design name; wells without a formation use the design's own values."
          },
          "unused": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A stage field.",
              "enum": [
                "stage_length_ft",
                "clusters_per_stage",
                "frac_rate_bbl_per_min"
              ]
            },
            "description": "The stage fields the request sent, on the design or any narrower layer, that the model set's models don't read, so nothing used them; only when there is one."
          }
        },
        "additionalProperties": false
      },
      "StreamForecast": {
        "description": "One stream's forecast: cumulative volume at each ip_day, or why it couldn't run.",
        "oneOf": [
          {
            "type": "object",
            "description": "A forecast stream.",
            "required": [
              "model_num",
              "target",
              "unit",
              "ip_days",
              "values",
              "missing"
            ],
            "properties": {
              "model_num": {
                "type": "string",
                "description": "Model that produced the forecast."
              },
              "target": {
                "type": "string",
                "description": "Model target column, as novi_oil."
              },
              "unit": {
                "type": "string",
                "description": "Volume unit: bbl for oil and water, mcf for gas.",
                "enum": [
                  "bbl",
                  "mcf"
                ]
              },
              "ip_days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "description": "Days since first production."
                },
                "description": "ip_days with a forecast, ascending."
              },
              "values": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Cumulative volume at the matching ip_day."
                },
                "description": "Cumulative volumes, one per ip_day."
              },
              "missing": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "Model feature name."
                },
                "description": "Model features that were blank for this well and fell back to the model's own handling."
              },
              "eur": {
                "$ref": "#/components/schemas/Eur",
                "description": "With eur: true, on oil and gas, and on water with eur_water: true: the EUR, fit on every ip_day of the forecast (before any ip_days filter)."
              },
              "bands": {
                "$ref": "#/components/schemas/StreamBands",
                "description": "With bands: true: the P10 (low) and P90 (high) cumulative curves on these ip_days, or why this stream has none."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "A stream that failed.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why this stream has no forecast."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "BoeForecast": {
        "description": "With boe: true: the forecast's BOE beside its streams, or why it has none.\n\nBOE is oil plus gas / 6 (6 mcf per bbl), on ip_days where both have a value; on a set serving one of them the other counts 0, and serving neither, BOE is 0.\n\nIts P10 adds oil's P10 and gas's P10 / 6 (P90 likewise). The models predict each stream apart, so this isn't the P10 of BOE itself; it is as wide as BOE's would be if oil and gas moved together. Novi's P10 is the low case. Totals add the BOE of the wells that have both oil and gas forecasts, and say how many in `wells`.",
        "oneOf": [
          {
            "type": "object",
            "description": "BOE.",
            "required": [
              "unit",
              "ip_days",
              "values"
            ],
            "properties": {
              "unit": {
                "type": "string",
                "description": "Always BOE.",
                "enum": [
                  "BOE"
                ]
              },
              "ip_days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "description": "Days since first production."
                },
                "description": "Oil's ip_days (with ip_days, only those asked for)."
              },
              "values": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Oil plus gas / 6 at the matching ip_day, to 0.1; null where either is null."
                },
                "description": "BOE cumulative volumes, one per ip_day."
              },
              "wells": {
                "type": "integer",
                "description": "On totals only: the wells summed, those whose own BOE is ok (both an oil and a gas forecast on the same ip_days). Oil's and gas's own totals may cover more wells.",
                "minimum": 1
              },
              "eur": {
                "$ref": "#/components/schemas/BoeEur",
                "description": "On a well's forecast with eur: true: oil's EUR plus gas's / 6. Totals have none: their BOE EUR is in totals[].eur.boe."
              },
              "bands": {
                "$ref": "#/components/schemas/BoeBands",
                "description": "With bands: true: BOE's P10 and P90, or why it has none. On totals, summed over the wells summed when every one has BOE bands."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No BOE.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why there is no BOE: a stream failed (named, oil before gas), oil and gas are on different ip_days, or on totals no well has both."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "BoeEur": {
        "description": "A BOE EUR: oil's EUR plus gas's / 6, or why there is none.",
        "oneOf": [
          {
            "type": "object",
            "description": "A BOE EUR.",
            "required": [
              "value",
              "days"
            ],
            "properties": {
              "value": {
                "type": "number",
                "description": "Oil EUR plus gas EUR / 6, to 0.1."
              },
              "days": {
                "type": "integer",
                "description": "The later of oil's and gas's EUR days."
              },
              "curve": {
                "$ref": "#/components/schemas/BoeEurCurve",
                "description": "With eur_curve, when oil's and gas's EURs both have curves: BOE's cumulative curve, or why there is none."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No BOE EUR.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why there is no BOE EUR: oil's or gas's EUR failed, named, oil before gas."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "BoeEurCurve": {
        "description": "With eur_curve: BOE's cumulative curve from the forecast's last ip_day to its EUR's days, or why there is none.",
        "oneOf": [
          {
            "type": "object",
            "description": "The BOE curve.",
            "required": [
              "step_days",
              "ip_days",
              "values"
            ],
            "properties": {
              "step_days": {
                "type": "integer",
                "description": "The streams' curve step: 30 for month, 360 for year.",
                "enum": [
                  30,
                  360
                ]
              },
              "ip_days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "description": "Days since first production."
                },
                "description": "The union of oil's and gas's curve ip_days, ascending: each stream's steps and its own EUR day, so the shorter stream's EUR day can fall between two steps."
              },
              "values": {
                "type": "array",
                "items": {
                  "type": "number",
                  "description": "BOE cumulative volume."
                },
                "description": "Oil's cumulative plus gas's / 6 at each ip_day, to 0.01: each stream linear between its curve points from its forecast's last value, and held at its EUR after its last point. The last is at the later EUR day: a stream whose curve ends there gives its last curve value (to 0.01), and one whose curve ended sooner its EUR, so it may differ from `value` in its last digit, as `value` is to 0.1."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No BOE curve.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why there is no BOE curve: oil's or gas's curve failed or is missing, named, oil before gas."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "BoeBand": {
        "type": "object",
        "description": "One BOE band: oil's band plus gas's band / 6.",
        "required": [
          "values"
        ],
        "properties": {
          "values": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "The band's oil plus gas / 6 at the matching ip_day, to 0.1; null where either is null."
            },
            "description": "One per ip_day of the BOE."
          },
          "eur": {
            "$ref": "#/components/schemas/BoeEur",
            "description": "With band_eur: true: this band's oil EUR plus gas EUR / 6."
          }
        },
        "additionalProperties": false
      },
      "BoeBands": {
        "description": "BOE's P10 and P90, or why it has none.\n\nBOE is oil plus gas / 6 (6 mcf per bbl), on ip_days where both have a value; on a set serving one of them the other counts 0, and serving neither, BOE is 0.\n\nIts P10 adds oil's P10 and gas's P10 / 6 (P90 likewise). The models predict each stream apart, so this isn't the P10 of BOE itself; it is as wide as BOE's would be if oil and gas moved together. Novi's P10 is the low case. Totals add the BOE of the wells that have both oil and gas forecasts, and say how many in `wells`.",
        "oneOf": [
          {
            "type": "object",
            "description": "BOE bands.",
            "required": [
              "p10",
              "p90"
            ],
            "properties": {
              "p10": {
                "$ref": "#/components/schemas/BoeBand",
                "description": "The low curve: oil's P10 plus gas's P10 / 6."
              },
              "p90": {
                "$ref": "#/components/schemas/BoeBand",
                "description": "The high curve: oil's P90 plus gas's P90 / 6."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No BOE bands.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why there are none: oil's or gas's bands failed (named, oil before gas), or on totals some wells summed have none."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "Forecast": {
        "description": "Cumulative oil (bbl), gas (mcf) and water (bbl) by ip_day, or why the well has no forecast (no formation).",
        "oneOf": [
          {
            "type": "object",
            "description": "Forecasts per stream. A v2 forecast carries the streams its model set serves (GET /model-sets `streams`), oil, gas and water on a set serving all three; a Legacy Forecast that forecast only some (Plan `streams`) carries only those.",
            "required": [],
            "properties": {
              "oil": {
                "$ref": "#/components/schemas/StreamForecast"
              },
              "gas": {
                "$ref": "#/components/schemas/StreamForecast"
              },
              "water": {
                "$ref": "#/components/schemas/StreamForecast"
              },
              "boe": {
                "$ref": "#/components/schemas/BoeForecast"
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No forecast.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why the well has no forecast."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "DesignForecast": {
        "description": "One design's forecast for the well: cumulative oil (bbl), gas (mcf) and water (bbl) by ip_day, or why there is none.",
        "oneOf": [
          {
            "type": "object",
            "description": "Forecasts per stream, and the checks of their inputs. A v2 forecast carries the streams its model set serves (GET /model-sets `streams`), oil, gas and water on a set serving all three; a Legacy Forecast that forecast only some (Plan `streams`) carries only those.",
            "required": [
              "design",
              "checks"
            ],
            "properties": {
              "design": {
                "type": "integer",
                "description": "The design, as its index in `designs`.",
                "minimum": 0
              },
              "oil": {
                "$ref": "#/components/schemas/StreamForecast"
              },
              "gas": {
                "$ref": "#/components/schemas/StreamForecast"
              },
              "water": {
                "$ref": "#/components/schemas/StreamForecast"
              },
              "boe": {
                "$ref": "#/components/schemas/BoeForecast"
              },
              "checks": {
                "$ref": "#/components/schemas/ForecastChecks"
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No forecast.",
            "required": [
              "design",
              "error"
            ],
            "properties": {
              "design": {
                "type": "integer",
                "description": "The design, as its index in `designs`.",
                "minimum": 0
              },
              "error": {
                "type": "string",
                "description": "Why the well has no forecast."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "ForecastChecks": {
        "description": "Inputs the model rarely or never saw in training, or why they weren't checked.\n\nEvery ip_day's row of this design is checked against the oil model's training statistics (on a set without oil, the first served stream's model: gas, else water); the streams share features. An input is out of range only when it is more than 5% of its training 1st to 99th percentile range outside that range. Neighbors' production (parent depletion near the well) is reported in `context` instead.",
        "oneOf": [
          {
            "type": "object",
            "description": "Checked inputs.",
            "required": [
              "available",
              "model_num",
              "flagged",
              "out_of_range",
              "missing",
              "unknown_formation"
            ],
            "properties": {
              "available": {
                "const": true,
                "description": "The inputs were checked."
              },
              "model_num": {
                "type": "string",
                "description": "Model whose training statistics were used: the oil model, or on a set without oil the first served stream's."
              },
              "flagged": {
                "type": "boolean",
                "description": "True when out_of_range, missing or unknown_formation reports anything; context doesn't set it. When true, show the flag beside any number you quote from this well and design."
              },
              "out_of_range": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/InputOutOfRange"
                },
                "description": "Numeric inputs outside training in any row, one per feature, in the model's feature order: say each is outside the model's training data, with its value and range.\n\nOutside means more than 5% of the training range (99th minus 1st percentile) below the 1st or above the 99th percentile of training. A feature whose two percentiles are equal has no margin. The value a feature takes for no such neighbor (days online -1, distances at the spacing defaults) isn't checked, and neighbors' production features are in `context`."
              },
              "context": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/InputOutOfRange"
                },
                "description": "Neighbors' production features (novi_spacing_sum_prior_*, novi_spacing_delgados_p*) below the 1st or above the 99th percentile of training in any row, with no margin. They don't set flagged; absent when there are none.\n\nOne per feature, in the model's feature order. They measure the parent depletion near the well: how much nearby parents have produced by its TIL, weighted by how close they are. It moves with where the lateral is drawn more than with completions, and a well drawn today near parents that have produced for years often reads above training. Say the well has more (or less) parent depletion nearby than nearly all training wells, not that an input is unusual."
              },
              "missing": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "Model feature name."
                },
                "description": "Inputs blank in any row, of those blank in under 5% of training rows (inputs often blank in training aren't listed)."
              },
              "unknown_formation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The target formation when the model has no training rows in it, else null."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "Inputs not checked.",
            "required": [
              "available",
              "reason"
            ],
            "properties": {
              "available": {
                "const": false,
                "description": "The inputs weren't checked."
              },
              "reason": {
                "type": "string",
                "description": "Why, as no training statistics for the model."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "InputOutOfRange": {
        "type": "object",
        "description": "An input outside the training range.",
        "required": [
          "feature",
          "value",
          "low",
          "high",
          "side"
        ],
        "properties": {
          "feature": {
            "type": "string",
            "description": "Model feature, as novi_lateral_length."
          },
          "value": {
            "type": "number",
            "description": "The value farthest outside the training range over the rows, in the feature's unit."
          },
          "low": {
            "type": "number",
            "description": "1st percentile of the feature in training, leaving out the features' no-neighbor value."
          },
          "high": {
            "type": "number",
            "description": "99th percentile of the feature in training, leaving out the features' no-neighbor value."
          },
          "side": {
            "type": "string",
            "description": "below low or above high.",
            "enum": [
              "below",
              "above"
            ]
          }
        },
        "additionalProperties": false
      },
      "ShapRow": {
        "type": "object",
        "description": "SHAP at one ip_day.",
        "required": [
          "ip_day",
          "expected_value",
          "values"
        ],
        "properties": {
          "ip_day": {
            "type": "integer",
            "description": "Days since first production."
          },
          "expected_value": {
            "type": [
              "number",
              "null"
            ],
            "description": "The model's average forecast at this ip_day (its baseline)."
          },
          "values": {
            "type": "object",
            "description": "Contribution of each feature (non-zero only), in the stream's unit; expected_value plus these approximates the forecast, exactly only where the model's SHAP is additive (`residual` says how far it is). With explain_top / top, the largest ones and `(other)`, the sum of the rest.",
            "additionalProperties": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "inputs": {
            "type": "object",
            "additionalProperties": {
              "type": [
                "number",
                "string",
                "null"
              ]
            },
            "description": "With explain_inputs (POST /forecasts) or inputs=true (plan well): the value of each feature `values` lists (not `(other)`) as the model read it in this ip_day's model row. Numbers are unrounded, in the feature's unit (GET /models/{model_num} lists each input with its training range); categories such as novi_formation are strings; null where the row had none."
          },
          "forecast": {
            "type": [
              "number",
              "null"
            ],
            "description": "With residual=true (plan well) or explain_residual (POST /forecasts): the forecast served at this ip_day for this design, in the stream's unit, the same number GET /plans/{id}/wells/{index} serves there (on POST /forecasts, the well's `forecasts[d]` value before `ip_days` cuts it); null where none is served."
          },
          "residual": {
            "type": [
              "number",
              "null"
            ],
            "description": "With residual=true or explain_residual: forecast − expected_value − the sum of values (of the uncut row, whatever top keeps), unrounded: the part of the forecast the SHAP values don't attribute. Null when forecast or expected_value is null."
          }
        },
        "additionalProperties": false
      },
      "ContributingWell": {
        "type": "object",
        "description": "A training well the forecast leans on.",
        "required": [
          "key",
          "weight",
          "well_name",
          "operator",
          "formation",
          "first_prod",
          "heel_lon",
          "heel_lat",
          "bhl_lon",
          "bhl_lat"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "Wellbore key; GET /wells/{key} has its details."
          },
          "weight": {
            "type": "number",
            "description": "Share of the forecast's tree weight.",
            "minimum": 0,
            "maximum": 1
          },
          "well_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Well name."
          },
          "operator": {
            "type": [
              "string",
              "null"
            ],
            "description": "Operator."
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Formation."
          },
          "first_prod": {
            "type": [
              "string",
              "null"
            ],
            "description": "First production date.",
            "format": "date"
          },
          "heel_lon": {
            "type": [
              "number",
              "null"
            ],
            "description": "Heel longitude."
          },
          "heel_lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Heel latitude."
          },
          "bhl_lon": {
            "type": [
              "number",
              "null"
            ],
            "description": "Bottom hole longitude."
          },
          "bhl_lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Bottom hole latitude."
          }
        },
        "additionalProperties": false
      },
      "StreamExplanation": {
        "description": "One stream model's explanation of the forecast, or why it couldn't run.",
        "oneOf": [
          {
            "type": "object",
            "description": "An explained stream.",
            "required": [
              "model_num",
              "unit",
              "shap",
              "contributing_wells",
              "other_weight"
            ],
            "properties": {
              "model_num": {
                "type": "string",
                "description": "Model explained."
              },
              "unit": {
                "type": "string",
                "description": "Volume unit of the contributions.",
                "enum": [
                  "bbl",
                  "mcf"
                ]
              },
              "shap": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ShapRow"
                },
                "description": "SHAP per ip_day, ascending."
              },
              "contributing_wells": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ContributingWell"
                },
                "description": "Training wells sharing the forecast's tree leaves, heaviest first (top 25, or explain_top / top). On a causal model set (GET /model-sets?include=model_type), they are the training wells sharing the leaves its baseline (associative) model's prediction used, weighted before the completion effect is applied. Empty when the model's fit has no tree weights: SHAP still explains the forecast."
              },
              "other_weight": {
                "type": "number",
                "description": "Weight of every other training well (1 minus the listed weights); 1 when the fit has no tree weights and `contributing_wells` is empty.",
                "minimum": 0,
                "maximum": 1
              },
              "weighted_wells": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "With weight_counts or explain_weight_counts: training wells with nonzero weight, of which `contributing_wells` lists the heaviest; null when the fit has no tree weights or the model worker sent no counts for it, 0 when every weight is 0.",
                "minimum": 0
              },
              "effective_wells": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "With weight_counts or explain_weight_counts: the effective number of training wells the weight rests on, 1/Σw² over every training well's weight (weights sum to 1), to 0.001. It equals `weighted_wells` when the weight is spread evenly and nears 1 when one well carries it; null when the fit has no tree weights, the model worker sent no counts for it or every weight is 0.",
                "minimum": 1
              },
              "weights_error": {
                "type": "string",
                "description": "With weight_counts or explain_weight_counts, when the fit has no tree weights: why, so `weighted_wells` and `effective_wells` are null; also when the model worker sent no counts for the fit."
              },
              "comparisons": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ExplanationComparison"
                },
                "description": "With compare or explain_compare: one per reference, in the order asked."
              },
              "analog_spread": {
                "$ref": "#/components/schemas/AnalogSpread",
                "description": "With spread or explain_spread: what the contributing wells actually produced, scaled to this lateral. For a fit without tree weights, `{error}` with the model's reason."
              },
              "analogs": {
                "$ref": "#/components/schemas/ModelAnalogs",
                "description": "With analogs or explain_analogs: the model's analog wells for this forecast and, when their measured coverage passes the gate, their spread; for fits with or without tree weights."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "A stream that failed.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why this stream has no explanation."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "ExplanationComparison": {
        "description": "This explanation rebased onto a reference, or why the reference has no baseline.",
        "oneOf": [
          {
            "type": "object",
            "description": "A comparison.",
            "required": [
              "reference",
              "formation",
              "label",
              "source",
              "rows"
            ],
            "properties": {
              "reference": {
                "type": "string",
                "description": "The reference.",
                "enum": [
                  "formation",
                  "dataset",
                  "analogs"
                ]
              },
              "formation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "With formation, the formation the reference covers; null for dataset; with analogs, this well's."
              },
              "label": {
                "type": "string",
                "description": "The reference in words, as Typical Wolfcamp A well."
              },
              "source": {
                "type": "string",
                "description": "The population the reference's mean SHAP is over, in words, as \"mean SHAP over the WOLFCAMP A wells of the existing wells the model explained (…), per ip_day\"."
              },
              "keys": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A wellbore key."
                },
                "description": "With analogs only: the wells averaged, nearest first, the first 15 (or fewer) of the stream's analogs list."
              },
              "rows": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "One ip_day.",
                  "required": [
                    "ip_day",
                    "wells",
                    "value",
                    "values"
                  ],
                  "properties": {
                    "ip_day": {
                      "type": "integer",
                      "description": "Days since first production."
                    },
                    "wells": {
                      "type": "integer",
                      "description": "Reference wells at this ip_day.",
                      "minimum": 0
                    },
                    "value": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "The reference wells' average model forecast here as SHAP gives it: their mean expected_value plus their mean contributions, in the stream's unit; with no stored mean expected_value, this well's expected_value plus their mean contributions (start_from says which). Null with fewer than 5 wells."
                    },
                    "start_from": {
                      "type": "string",
                      "description": "Where value starts: reference, the reference wells' stored mean expected_value; well, this well's own expected_value, where no mean is stored (values then has no (baseline)). Only on a row with a value.",
                      "enum": [
                        "reference",
                        "well"
                      ]
                    },
                    "values": {
                      "type": "object",
                      "description": "This well's contribution minus the reference's mean contribution, by feature, in the stream's unit. value plus these is this well's expected_value plus its SHAP values, which approximates its forecast.\n\n- `(baseline)`, when it rounds to non-zero: this well's expected_value less the reference wells' mean, which SHAP assigns to no input. In models that scale by lateral length it is mostly this well's lateral against theirs.\n- Add the SHAP row's residual for the forecast.\n- With top, the largest feature differences and `(other)`, plus `(baseline)`, which top never counts or folds.",
                      "additionalProperties": {
                        "type": [
                          "number",
                          "null"
                        ]
                      }
                    }
                  },
                  "additionalProperties": false
                },
                "description": "One per SHAP row (one with ip_day)."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No comparison.",
            "required": [
              "reference",
              "error"
            ],
            "properties": {
              "reference": {
                "type": "string",
                "description": "The reference.",
                "enum": [
                  "formation",
                  "dataset",
                  "analogs"
                ]
              },
              "error": {
                "type": "string",
                "description": "Why there is no baseline, as the model has no baseline for DEAN."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "SpreadDriver": {
        "type": "object",
        "description": "The input that moves the served forecast furthest the way an analog spread row's flag points.",
        "required": [
          "feature",
          "value",
          "reference"
        ],
        "properties": {
          "feature": {
            "type": "string",
            "description": "The model input, as novi_spacing_parent_daysonline; GET /models/{model_num} lists them."
          },
          "value": {
            "type": "number",
            "description": "Its contribution in the stream's unit, rounded to 0.001: negative when the flag is below, positive when above. Against the formation's typical well with reference formation, else the raw SHAP value."
          },
          "reference": {
            "type": "string",
            "description": "What the contribution is measured against: formation, the typical well of this well's formation at this ip_day (its mean SHAP over at least 5 wells, as compare=formation); model, the model's average well (the raw SHAP value).",
            "enum": [
              "formation",
              "model"
            ]
          }
        },
        "additionalProperties": false
      },
      "AnalogSpread": {
        "description": "The analog spread, or why there is none.",
        "oneOf": [
          {
            "type": "object",
            "description": "A spread.",
            "required": [
              "basis",
              "lateral_length_ft",
              "wells_considered",
              "min_wells",
              "rows"
            ],
            "properties": {
              "basis": {
                "type": "string",
                "description": "What the spread is of, in words."
              },
              "lateral_length_ft": {
                "type": "integer",
                "description": "This well's lateral, ft: every contributing well is scaled to it."
              },
              "wells_considered": {
                "type": "integer",
                "description": "Contributing wells taken (the 50 heaviest).",
                "minimum": 0
              },
              "min_wells": {
                "type": "integer",
                "description": "Fewest wells for quantiles.",
                "minimum": 1
              },
              "rows": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "One ip_day.",
                  "required": [
                    "ip_day",
                    "wells",
                    "q10",
                    "q50",
                    "q90",
                    "forecast"
                  ],
                  "properties": {
                    "ip_day": {
                      "type": "integer",
                      "description": "Days since first production."
                    },
                    "wells": {
                      "type": "integer",
                      "description": "Contributing wells whose production reached this ip_day.",
                      "minimum": 0
                    },
                    "q10": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "10th percentile of their scaled cumulatives, the low end; null with fewer than min_wells."
                    },
                    "q50": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "Median; null with fewer than min_wells."
                    },
                    "q90": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "90th percentile, the high end; null with fewer than min_wells."
                    },
                    "forecast": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "enum": [
                        "below",
                        "within",
                        "above",
                        null
                      ],
                      "description": "Where the served forecast at this ip_day falls against q10 to q90; null without quantiles or a served forecast."
                    },
                    "driver": {
                      "anyOf": [
                        {
                          "$ref": "#/components/schemas/SpreadDriver"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "With driver=true or explain_driver: the input that moves the forecast furthest the way `forecast` points; null when it is within or null, or when no input moves it that way."
                    }
                  },
                  "additionalProperties": false
                },
                "description": "One per ip_day of the SHAP rows."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No spread.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why there is no spread."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "ModelAnalogWell": {
        "type": "object",
        "description": "A model analog; analogs_detail adds its cumulatives and inputs.",
        "required": [
          "key",
          "distance",
          "well_name",
          "operator",
          "formation",
          "first_prod",
          "lateral_length",
          "heel_lon",
          "heel_lat",
          "bhl_lon",
          "bhl_lat"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "Wellbore key; GET /wells/{key} has its details."
          },
          "distance": {
            "type": "number",
            "description": "Its distance from this forecast in the model's weighted standard scores; 0 is the same inputs.",
            "minimum": 0
          },
          "well_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Well name."
          },
          "operator": {
            "type": [
              "string",
              "null"
            ],
            "description": "Operator."
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Formation."
          },
          "first_prod": {
            "type": [
              "string",
              "null"
            ],
            "description": "First production date.",
            "format": "date"
          },
          "lateral_length": {
            "type": [
              "number",
              "null"
            ],
            "description": "Lateral length, ft."
          },
          "heel_lon": {
            "type": [
              "number",
              "null"
            ],
            "description": "Heel longitude."
          },
          "heel_lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Heel latitude."
          },
          "bhl_lon": {
            "type": [
              "number",
              "null"
            ],
            "description": "Bottom hole longitude."
          },
          "bhl_lat": {
            "type": [
              "number",
              "null"
            ],
            "description": "Bottom hole latitude."
          },
          "cum_oil_360": {
            "type": [
              "number",
              "null"
            ],
            "description": "With analogs_detail: its actual cumulative oil at ip_day 360, bbl, unscaled; null when it hasn't produced that long."
          },
          "cum_oil_720": {
            "type": [
              "number",
              "null"
            ],
            "description": "With analogs_detail: its actual cumulative oil at ip_day 720, bbl, unscaled; null when it hasn't produced that long."
          },
          "cum_oil_1080": {
            "type": [
              "number",
              "null"
            ],
            "description": "With analogs_detail: its actual cumulative oil at ip_day 1080, bbl, unscaled; null when it hasn't produced that long."
          },
          "cum_gas_360": {
            "type": [
              "number",
              "null"
            ],
            "description": "With analogs_detail: its actual cumulative gas at ip_day 360, mcf, unscaled; null when it hasn't produced that long."
          },
          "cum_gas_720": {
            "type": [
              "number",
              "null"
            ],
            "description": "With analogs_detail: its actual cumulative gas at ip_day 720, mcf, unscaled; null when it hasn't produced that long."
          },
          "cum_gas_1080": {
            "type": [
              "number",
              "null"
            ],
            "description": "With analogs_detail: its actual cumulative gas at ip_day 1080, mcf, unscaled; null when it hasn't produced that long."
          },
          "cum_oil_life": {
            "type": [
              "number",
              "null"
            ],
            "description": "With analogs_detail: its cumulative oil to date, bbl."
          },
          "cum_gas_life": {
            "type": [
              "number",
              "null"
            ],
            "description": "With analogs_detail: its cumulative gas to date, mcf."
          },
          "eur_oil": {
            "type": [
              "number",
              "null"
            ],
            "description": "With analogs_detail: its oil EUR, bbl, from the decline fit on its actual cumulative oil at every 30-day ip_day it has produced (`analogs.eur`); null when it can't be fit.\n\nNull when the well lacks production at any 30-day ip_day from 30 to 360 (its first 12 months), has a history longer than `eur_years`, or the fit failed, and when the EUR is below its cumulative to date or not above its last 30-day cumulative (a flat extension, kept only after 90 days without production)."
          },
          "eur_gas": {
            "type": [
              "number",
              "null"
            ],
            "description": "With analogs_detail: its gas EUR, mcf, as `eur_oil` is fit."
          },
          "inputs": {
            "$ref": "#/components/schemas/ModelAnalogInputs",
            "description": "With analogs_detail: the model's raw inputs for this well, in `weights` order."
          }
        },
        "additionalProperties": false
      },
      "ModelAnalogsEur": {
        "description": "How the analogs' EURs were fit, or why they weren't; never fails the explanation.",
        "oneOf": [
          {
            "type": "object",
            "description": "The fit.",
            "required": [
              "basis",
              "decline",
              "fitted"
            ],
            "properties": {
              "basis": {
                "type": "string",
                "description": "In words: the fit, the curves it ran on, the settings' source, what an analog needs to get an EUR (as ModelAnalogWell `eur_oil` says), how many got one and, by reason, how many didn't."
              },
              "decline": {
                "$ref": "#/components/schemas/Decline",
                "description": "The decline settings used: each well's own once a layer below the plan reaches any well with a setting other than `water`; else a plan's own when it was made with eur: true, a forecast's decline with eur: true, else GET /dataset eur.defaults."
              },
              "fitted": {
                "type": "object",
                "description": "How many of the listed analogs got an EUR, per stream.",
                "required": [
                  "oil",
                  "gas"
                ],
                "properties": {
                  "oil": {
                    "type": "integer",
                    "description": "Analogs with an eur_oil.",
                    "minimum": 0
                  },
                  "gas": {
                    "type": "integer",
                    "description": "Analogs with an eur_gas.",
                    "minimum": 0
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No EUR.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why there is no EUR: the server has none (as eur: true answers 503), or the fit failed."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "ModelAnalogInputs": {
        "type": "object",
        "additionalProperties": {
          "type": [
            "number",
            "null"
          ]
        },
        "description": "A model's raw inputs at the ip_day the analog distance uses, by feature name, keys in `weights` order (heaviest first; JSON keeps that order for feature names that aren't whole numbers, so read them by `weights`); null where the well has no value."
      },
      "ModelAnalogs": {
        "description": "The model's analogs of this forecast, or `{error}` saying why there are none: the dataset has no analog index, or the analog weights leave nothing to rank them by (all 0, or only on inputs that don't vary across this well's candidates).",
        "oneOf": [
          {
            "type": "object",
            "description": "The model analogs.",
            "required": [
              "method",
              "note",
              "basis",
              "formation",
              "child",
              "lateral_band_pct",
              "candidates",
              "weights",
              "wells",
              "coverage",
              "spread"
            ],
            "properties": {
              "method": {
                "type": "string",
                "description": "How they were chosen: two stages, hard filters then the distance over standard scores weighted by the model's mean |SHAP|, unless `analog_weights` is present, then by those weights for the inputs it names.",
                "enum": [
                  "shap_weighted"
                ]
              },
              "note": {
                "type": "string",
                "description": "Always \"Analog spread, not the model's uncertainty\"."
              },
              "basis": {
                "type": "string",
                "description": "Who they are, in words: the filters, how many wells passed them and the ip_day of the distance."
              },
              "formation": {
                "type": "string",
                "description": "The formation they share with this well."
              },
              "child": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "This well's parent (false) or child (true) status, which they share; null when its spacing features don't say, and then both count."
              },
              "lateral_band_pct": {
                "type": [
                  "integer",
                  "null"
                ],
                "enum": [
                  25,
                  50,
                  100,
                  null
                ],
                "description": "How far their laterals may be from this well's, %: 25, widened to 50 then 100 until 5 wells pass; null when fewer pass even at 100, and then any lateral counts."
              },
              "candidates": {
                "type": "integer",
                "description": "Training wells that passed the filters; the nearest 50 are listed.",
                "minimum": 0
              },
              "weights": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "One feature's weight.",
                  "required": [
                    "feature",
                    "weight"
                  ],
                  "properties": {
                    "feature": {
                      "type": "string",
                      "description": "A numeric model input."
                    },
                    "weight": {
                      "type": "number",
                      "description": "Its share of the distance: the model's mean |SHAP| for it at its last ip_day, over the wells the build explained, or with analog_weights the share the distance used; they sum to 1. Formation is a filter, not a weight.",
                      "minimum": 0,
                      "maximum": 1
                    },
                    "model_weight": {
                      "type": "number",
                      "description": "With analog_weights: the model's own weight for it, as `weight` is without them.",
                      "minimum": 0,
                      "maximum": 1
                    }
                  },
                  "additionalProperties": false
                },
                "description": "Every numeric model input, heaviest first."
              },
              "analog_weights": {
                "type": "object",
                "additionalProperties": {
                  "type": "number",
                  "minimum": 0
                },
                "description": "With analog_weights, when it names some of this model's inputs: the weights sent for them, as sent; the distance then used `weights`, these shares with the rest shared by the model's other inputs, or these rescaled to 1 when nothing takes the rest. Absent otherwise."
              },
              "inputs": {
                "$ref": "#/components/schemas/ModelAnalogInputs",
                "description": "With analogs_detail: this forecast's own inputs, as each well's, so a table can put this well first."
              },
              "eur": {
                "$ref": "#/components/schemas/ModelAnalogsEur",
                "description": "With analogs_detail: how the wells' `eur_oil` and `eur_gas` were fit, or why there are none."
              },
              "wells": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ModelAnalogWell"
                },
                "description": "Up to 50, nearest first (ties by key); `top` doesn't cut them.",
                "maxItems": 50
              },
              "coverage": {
                "anyOf": [
                  {
                    "type": "object",
                    "description": "The spread's measured coverage.",
                    "required": [
                      "ip_day",
                      "k",
                      "nominal",
                      "measured",
                      "wells",
                      "gate",
                      "shown"
                    ],
                    "properties": {
                      "ip_day": {
                        "type": "integer",
                        "description": "The ip_day measured: the model's last one that enough held-out wells reach with production."
                      },
                      "k": {
                        "type": "integer",
                        "description": "Analogs per held-out well, as here."
                      },
                      "nominal": {
                        "type": "number",
                        "description": "The share q10 to q90 would hold if it were a calibrated 80% interval."
                      },
                      "measured": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "The share of held-out wells whose actual production at ip_day fell within their own analogs' q10 to q90, each against the training wells alone; to 0.001."
                      },
                      "wells": {
                        "type": "integer",
                        "description": "Held-out wells measured (each with at least 5 analogs with production at ip_day).",
                        "minimum": 0
                      },
                      "gate": {
                        "type": "object",
                        "description": "What the spread must pass to be shown.",
                        "required": [
                          "min",
                          "max",
                          "wells"
                        ],
                        "properties": {
                          "min": {
                            "type": "number",
                            "description": "Lowest measured share shown."
                          },
                          "max": {
                            "type": "number",
                            "description": "Highest measured share shown."
                          },
                          "wells": {
                            "type": "integer",
                            "description": "Fewest held-out wells measured."
                          }
                        },
                        "additionalProperties": false
                      },
                      "shown": {
                        "type": "boolean",
                        "description": "Whether `measured` and `wells` pass the gate, so `spread` is given; with `analog_weights`, only when the wells listed are the ones the model's weights list, as coverage was measured with those."
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "How often this model's analog spread held held-out wells' actual production, measured once when the index was built; null when the build has no held-out wells with production."
              },
              "spread": {
                "$ref": "#/components/schemas/AnalogSpread",
                "description": "With `coverage.shown`, q10, q50 and q90 of these wells' actual cumulatives, each scaled to this well's lateral, as `analog_spread`: an analog spread, not the model's uncertainty.\n\n`{error}` instead:\n\n- without `coverage.shown`, saying what was measured;\n- with fewer than 5 analogs listed (`candidates` under 5), whatever `coverage` says, saying how many training wells passed the filters;\n- with `analog_weights`, unless the wells listed are the ones the model's weights list, since coverage was measured with the model's weights."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No analogs.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why there are none, as the dataset has no analog index."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "Explanation": {
        "description": "One design's explanation of the well's forecast, per stream, or why there is none.",
        "oneOf": [
          {
            "type": "object",
            "description": "Explanations per stream. Only the streams the model set serves (GET /model-sets `streams`): a set serving gas alone answers gas alone.",
            "required": [
              "design"
            ],
            "properties": {
              "design": {
                "type": "integer",
                "description": "The design, as its index in `designs`.",
                "minimum": 0
              },
              "oil": {
                "$ref": "#/components/schemas/StreamExplanation"
              },
              "gas": {
                "$ref": "#/components/schemas/StreamExplanation"
              },
              "water": {
                "$ref": "#/components/schemas/StreamExplanation"
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No explanation.",
            "required": [
              "design",
              "error"
            ],
            "properties": {
              "design": {
                "type": "integer",
                "description": "The design, as its index in `designs`.",
                "minimum": 0
              },
              "error": {
                "type": "string",
                "description": "Why there is no explanation (no forecast)."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "PlanWellExplanation": {
        "description": "One design's explanation of the well's forecast, per stream, or why there is none.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/PlanWellExplanationStreams"
          },
          {
            "$ref": "#/components/schemas/PlanWellExplanationError"
          }
        ]
      },
      "PlanWellExplanationStreams": {
        "type": "object",
        "description": "Explanations per stream. Only the streams the model set serves (GET /model-sets `streams`): a set serving gas alone answers gas alone.",
        "required": [
          "index",
          "label",
          "design"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "The well's position in the plan.",
            "minimum": 0
          },
          "label": {
            "type": "string",
            "description": "Display name, as Plan well 2."
          },
          "name": {
            "type": "string",
            "description": "The name the request gave the well, trimmed; only when it gave one. `label` doesn't change."
          },
          "design": {
            "type": "integer",
            "description": "The design, as its index in `designs`.",
            "minimum": 0
          },
          "oil": {
            "$ref": "#/components/schemas/StreamExplanation"
          },
          "gas": {
            "$ref": "#/components/schemas/StreamExplanation"
          },
          "water": {
            "$ref": "#/components/schemas/StreamExplanation"
          }
        },
        "additionalProperties": false
      },
      "PlanWellExplanationError": {
        "type": "object",
        "description": "No explanation.",
        "required": [
          "index",
          "label",
          "design",
          "error"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "The well's position in the plan.",
            "minimum": 0
          },
          "label": {
            "type": "string",
            "description": "Display name, as Plan well 2."
          },
          "name": {
            "type": "string",
            "description": "The name the request gave the well, trimmed; only when it gave one. `label` doesn't change."
          },
          "design": {
            "type": "integer",
            "description": "The design, as its index in `designs`.",
            "minimum": 0
          },
          "error": {
            "type": "string",
            "description": "Why there is no explanation (no forecast)."
          }
        },
        "additionalProperties": false
      },
      "DesignNode": {
        "type": "object",
        "description": "The drawn well's spacing node.",
        "required": [
          "azimuth",
          "heel",
          "heel_is_virtual",
          "pad_wells"
        ],
        "properties": {
          "azimuth": {
            "type": [
              "number",
              "null"
            ],
            "description": "Lateral azimuth, degrees."
          },
          "heel": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "Degrees."
            },
            "description": "Heel [lng, lat]: the surface hole, or estimated from a pad of existing wells within 200 ft.",
            "minItems": 2,
            "maxItems": 2
          },
          "heel_is_virtual": {
            "type": "boolean",
            "description": "Heel estimated rather than drawn."
          },
          "pad_wells": {
            "type": "integer",
            "description": "Existing wells on the same pad."
          }
        },
        "additionalProperties": false
      },
      "Eur": {
        "description": "One stream's EUR: the forecast's cumulative extended by the decline fit, or why it couldn't be fit.",
        "oneOf": [
          {
            "type": "object",
            "description": "An EUR.",
            "required": [
              "value",
              "days",
              "arps"
            ],
            "properties": {
              "value": {
                "type": "number",
                "description": "Cumulative volume at days: the forecast to its last ip_day, then the decline curve (bbl for oil, mcf for gas)."
              },
              "days": {
                "type": "integer",
                "description": "ip_day the EUR is at: the last 30-day step within eur_years."
              },
              "arps": {
                "type": "object",
                "description": "The modified Arps curve fitted to the extension, not to the 3-year forecast itself.",
                "required": [
                  "q_i",
                  "d",
                  "b",
                  "terminal_year"
                ],
                "properties": {
                  "q_i": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "Initial rate of the extension fit, per day (0 for a dry well)."
                  },
                  "d": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "Nominal decline of the extension fit, per day."
                  },
                  "b": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "Hyperbolic exponent of the extension fit."
                  },
                  "terminal_year": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "Year the curve switches to terminal (exponential) decline."
                  }
                },
                "additionalProperties": false
              },
              "curve": {
                "$ref": "#/components/schemas/EurCurve",
                "description": "With eur_curve: the cumulative from the forecast's last ip_day to days."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No EUR.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why there is no EUR, as the decline fit reports it."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "EurCurve": {
        "description": "With eur_curve: an EUR's cumulative curve from the forecast's last ip_day to the EUR's days, or why the fit returned none.",
        "oneOf": [
          {
            "type": "object",
            "description": "The curve.",
            "required": [
              "step_days",
              "ip_days",
              "values"
            ],
            "properties": {
              "step_days": {
                "type": "integer",
                "description": "30 for month, 360 for year.",
                "enum": [
                  30,
                  360
                ]
              },
              "ip_days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "description": "Days since first production."
                },
                "description": "From the forecast's last ip_day plus one step to the EUR's days, ascending: every 30 days (month), or every 360 days and the EUR's days last (year)."
              },
              "values": {
                "type": "array",
                "items": {
                  "type": "number",
                  "description": "Cumulative volume, bbl for oil and mcf for gas."
                },
                "description": "Cumulative volumes to 0.01, one per ip_day, continuing the forecast's values; the last is the EUR's value to 0.01."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No curve.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why there is no curve: the decline fit returned no extension, the forecast worker failed to fit one again (POST /forecasts), or the extension doesn't end on this EUR at its day on the forecast's month grid."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "Decline": {
        "type": "object",
        "description": "Decline fit settings used. oil and gas, when present, are the settings each stream was fit with; without them, both were fit with these. water, when present, is the echo of eur_water.",
        "required": [
          "eur_years",
          "terminal_decline",
          "b_min",
          "b_max"
        ],
        "properties": {
          "eur_years": {
            "type": "integer",
            "description": "Years to EUR: the extension runs to the last 30-day step within eur_years × 365 days.",
            "minimum": 10,
            "maximum": 50
          },
          "terminal_decline": {
            "type": "number",
            "description": "Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.",
            "minimum": 0.01,
            "maximum": 0.2
          },
          "b_min": {
            "type": "number",
            "description": "Lowest hyperbolic b the fit may use; below b_max.",
            "minimum": 0,
            "maximum": 2.5
          },
          "b_max": {
            "type": "number",
            "description": "Highest hyperbolic b the fit may use; above b_min.",
            "minimum": 0,
            "maximum": 2.5
          },
          "oil": {
            "$ref": "#/components/schemas/StreamDecline",
            "description": "With per-stream settings, the settings oil was fit with."
          },
          "gas": {
            "$ref": "#/components/schemas/StreamDecline",
            "description": "With per-stream settings, the settings gas was fit with."
          },
          "water": {
            "$ref": "#/components/schemas/StreamDecline",
            "description": "Only with eur_water: true: the settings water was fit with. Its presence is the echo of the flag."
          },
          "per_well": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Only when a well has its own settings: these are the request's or plan's, not every well's; `inputs.resolved.decline` gives each well's."
          }
        },
        "additionalProperties": false
      },
      "DeclineSettings": {
        "type": "object",
        "description": "Decline fit settings; any left out take the defaults. oil or gas (even empty) sets per-stream settings: each stream takes its own value, else the one here, else the default. These must be a valid set on their own, even when oil and gas override them. eur_years is shared.",
        "required": [],
        "properties": {
          "eur_years": {
            "type": "integer",
            "description": "Years to EUR: the extension runs to the last 30-day step within eur_years × 365 days.",
            "minimum": 10,
            "maximum": 50
          },
          "terminal_decline": {
            "type": "number",
            "description": "Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.",
            "minimum": 0.01,
            "maximum": 0.2
          },
          "b_min": {
            "type": "number",
            "description": "Lowest hyperbolic b the fit may use; below b_max.",
            "minimum": 0,
            "maximum": 2.5
          },
          "b_max": {
            "type": "number",
            "description": "Highest hyperbolic b the fit may use; above b_min.",
            "minimum": 0,
            "maximum": 2.5
          },
          "oil": {
            "$ref": "#/components/schemas/StreamDeclineSettings",
            "description": "Oil's own settings over these."
          },
          "gas": {
            "$ref": "#/components/schemas/StreamDeclineSettings",
            "description": "Gas's own settings over these."
          },
          "water": {
            "$ref": "#/components/schemas/StreamDeclineSettings",
            "description": "Water's own settings over these, only with eur_water: true, else a 400. Unlike oil and gas it doesn't set per-stream settings: oil and gas keep theirs and their calls."
          }
        },
        "additionalProperties": false
      },
      "StreamDecline": {
        "type": "object",
        "description": "One stream's decline fit settings, as fit.",
        "required": [
          "terminal_decline",
          "b_min",
          "b_max"
        ],
        "properties": {
          "terminal_decline": {
            "type": "number",
            "description": "Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.",
            "minimum": 0.01,
            "maximum": 0.2
          },
          "b_min": {
            "type": "number",
            "description": "Lowest hyperbolic b the fit may use; below b_max.",
            "minimum": 0,
            "maximum": 2.5
          },
          "b_max": {
            "type": "number",
            "description": "Highest hyperbolic b the fit may use; above b_min.",
            "minimum": 0,
            "maximum": 2.5
          }
        },
        "additionalProperties": false
      },
      "Band": {
        "type": "object",
        "description": "One band curve: cumulative volume by ip_day, never decreasing.",
        "required": [
          "values"
        ],
        "properties": {
          "values": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "Cumulative volume at the matching ip_day."
            },
            "description": "The band's cumulative volumes, one per ip_day of the stream."
          },
          "eur": {
            "$ref": "#/components/schemas/Eur",
            "description": "With band_eur: true, on oil and gas, and on water with eur_water: true: this band's EUR, fit like the forecast's (every ip_day, the same decline settings)."
          }
        },
        "additionalProperties": false
      },
      "StreamBands": {
        "description": "A stream forecast's P10/P90 bands, or why it has none (no stored bands fit for its model).",
        "oneOf": [
          {
            "type": "object",
            "description": "Bands: Novi's predrill bands (split conformal, safe variant), the conformal P10 (low) and P90 (high) at each ip_day around this forecast, stabilized from their rates so each stays cumulative. They usually bracket the forecast but aren't guaranteed to.",
            "required": [
              "p10",
              "p90"
            ],
            "properties": {
              "p10": {
                "$ref": "#/components/schemas/Band",
                "description": "The low curve (P10 in Novi's convention): the conformal lower bound at each ip_day, stabilized. Usually below the forecast, but not always: it is rebuilt from non-negative rates, so it can sit above the forecast where the forecast's cumulative dips."
              },
              "p90": {
                "$ref": "#/components/schemas/Band",
                "description": "The high curve (P90 in Novi's convention): the conformal upper bound at each ip_day, stabilized. Usually above the forecast, but not guaranteed to be."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No bands.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why this stream has no bands."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "BandsEcho": {
        "type": "object",
        "description": "With bands: true, the bands every forecast carries.",
        "required": [
          "percentiles",
          "method",
          "eur"
        ],
        "properties": {
          "percentiles": {
            "type": "array",
            "description": "The bands' percentiles: 10 (low) and 90 (high).",
            "prefixItems": [
              {
                "type": "integer",
                "description": "The low curve's percentile.",
                "const": 10
              },
              {
                "type": "integer",
                "description": "The high curve's percentile.",
                "const": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "method": {
            "type": "string",
            "description": "How the bands are made: Novi's predrill bands (split conformal, safe variant)."
          },
          "eur": {
            "type": "boolean",
            "description": "Whether each oil and gas band, and water's with eur_water, has its EUR (band_eur)."
          }
        },
        "additionalProperties": false
      },
      "DatasetBands": {
        "type": "object",
        "description": "P10/P90 bands on this server.",
        "required": [
          "available",
          "method",
          "percentiles",
          "streams",
          "reason"
        ],
        "properties": {
          "available": {
            "type": "boolean",
            "description": "Whether any stream has bands here (its model has a stored bands fit); bands: true answers 503 when false."
          },
          "method": {
            "type": [
              "string",
              "null"
            ],
            "description": "Novi's predrill bands (split conformal, safe variant); null when unavailable."
          },
          "percentiles": {
            "type": "array",
            "description": "Bands' percentiles: p10 is the low curve and p90 the high one (Novi's convention).",
            "prefixItems": [
              {
                "type": "integer",
                "description": "The low curve's percentile.",
                "const": 10
              },
              {
                "type": "integer",
                "description": "The high curve's percentile.",
                "const": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "streams": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Stream.",
              "enum": [
                "oil",
                "gas",
                "water"
              ]
            },
            "description": "Streams whose model has bands, among those the set serves; the others answer each forecast with a bands error."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why bands are unavailable, or which streams have none and why; null when every stream has them."
          }
        },
        "additionalProperties": false
      },
      "DatasetDepletionChain": {
        "type": "object",
        "description": "The depletion chain on this server.",
        "required": [
          "available",
          "features",
          "neighbor_production"
        ],
        "properties": {
          "available": {
            "type": "boolean",
            "description": "Whether a served model reads neighbors' production, so the depletion chain changes forecasts. When true, POST /plans chains a dated plan unless it sends depletion_chain: false; when false, every plan runs without it, also one sent with depletion_chain: true."
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Feature column."
            },
            "description": "The models' features that read neighbors' production: the spacing features novi_spacing_sum_prior_* and novi_spacing_delgados_p*."
          },
          "neighbor_production": {
            "type": "string",
            "description": "Where existing (PDP) parents' production comes from, for every forecast and plan on this set: `history` is their production to the dataset's as_of, held flat after; `extended` continues it with Novi's production forecast for each existing well past its history.",
            "enum": [
              "history",
              "extended"
            ]
          }
        },
        "additionalProperties": false
      },
      "DepletionChainEcho": {
        "type": "object",
        "description": "What a plan's depletion chain read and did. A chained well's GET /plans/{id}/wells/{index} `features` are its first design's chained values, while its `spacing.neighbors` edge-level `prior_*` fields are the first pass's, where a planned parent's production reads as 0.",
        "required": [
          "applied",
          "reason",
          "features",
          "buckets",
          "waves",
          "planned_parents",
          "neighbor_production",
          "extension"
        ],
        "properties": {
          "applied": {
            "type": "boolean",
            "description": "Whether the chain ran: false when no served model reads neighbors' production, and the plan then ran as without it."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why the chain didn't run; null when it did."
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Feature column."
            },
            "description": "The served models' features the chain feeds, as GET /dataset depletion_chain lists them."
          },
          "buckets": {
            "type": "integer",
            "description": "Calendar months the plan's TIL dates fall in. Wells without a til_date are TIL on the plan's start day.",
            "minimum": 1
          },
          "waves": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Waves after the plan's first pass: a well with planned parents is re-forecast one wave after its deepest one. null until every well is spaced (0 from the start when every TIL is in one calendar month), or when not applied.",
            "minimum": 0
          },
          "planned_parents": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Plan wells that are a parent of a later-month plan well, so their P50 feeds it. null until every well is spaced (0 from the start when every TIL is in one calendar month), or when not applied.",
            "minimum": 0
          },
          "neighbor_production": {
            "type": "string",
            "description": "Where existing (PDP) parents' production came from: `history` is their production to the dataset's as_of, held flat after; `extended` continues it with Novi's production forecast for each existing well past its history.",
            "enum": [
              "history",
              "extended"
            ]
          },
          "extension": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Decline"
              },
              {
                "type": "null"
              }
            ],
            "description": "The decline settings a planned parent was extended with where a later well reads it past its 1,080-day forecast (the plan's decline echo with eur, else Novi's defaults, and always the base settings for water, so never a `water`); null while none has been. With `per_well` these are the plan's, and a parent with its own settings was extended with those: read each well's `inputs.resolved.decline`."
          }
        },
        "additionalProperties": false
      },
      "BandEurTotal": {
        "type": "object",
        "description": "A stream band's EUR over the plan, summed per well: a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan.",
        "required": [
          "value",
          "wells"
        ],
        "properties": {
          "value": {
            "type": [
              "number",
              "null"
            ],
            "description": "This band's EUR summed over the wells with one; null when none has."
          },
          "wells": {
            "type": "integer",
            "description": "Wells with this band's EUR."
          }
        },
        "additionalProperties": false
      },
      "ByDateStream": {
        "description": "One stream's plan total by date, or why there is none.",
        "oneOf": [
          {
            "type": "object",
            "description": "Cumulative volumes by date.",
            "required": [
              "values"
            ],
            "properties": {
              "values": {
                "type": "array",
                "items": {
                  "type": "number",
                  "description": "Cumulative volume over the plan's wells on the matching date."
                },
                "description": "One per date."
              },
              "bands": {
                "type": "object",
                "description": "With bands: true, the wells' P10s and P90s by date the same way, when every well has them: a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan.",
                "required": [
                  "p10",
                  "p90"
                ],
                "properties": {
                  "p10": {
                    "type": "array",
                    "items": {
                      "type": "number",
                      "description": "Cumulative P10."
                    },
                    "description": "One per date."
                  },
                  "p90": {
                    "type": "array",
                    "items": {
                      "type": "number",
                      "description": "Cumulative P90."
                    },
                    "description": "One per date."
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No total.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why this stream has no total (no well has its forecast)."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "PlanByDate": {
        "type": "object",
        "description": "A plan with TIL dates, summed by calendar date: on each date every well adds 0 before its TIL date, its cumulative forecast interpolated linearly between its ip_days (0 on its TIL date, ip_day N at TIL plus N days) and its last value after them. Wells without a date are TIL the day the plan was made.",
        "required": [
          "dates",
          "horizon_days",
          "forecast"
        ],
        "properties": {
          "dates": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A month start, YYYY-MM-01.",
              "format": "date"
            },
            "description": "Month starts from the earliest TIL date's month through the first one on or after the latest TIL date plus horizon_days."
          },
          "horizon_days": {
            "type": "integer",
            "description": "The forecast horizon the dates run past the latest TIL: 1,080 days."
          },
          "forecast": {
            "type": "object",
            "description": "Per stream. A v2 forecast carries the streams its model set serves (GET /model-sets `streams`), oil, gas and water on a set serving all three; a Legacy Forecast that forecast only some (Plan `streams`) carries only those.",
            "required": [],
            "properties": {
              "oil": {
                "$ref": "#/components/schemas/ByDateStream"
              },
              "gas": {
                "$ref": "#/components/schemas/ByDateStream"
              },
              "water": {
                "$ref": "#/components/schemas/ByDateStream"
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "StreamDeclineSettings": {
        "type": "object",
        "description": "One stream's decline fit settings; any left out take decline's.",
        "required": [],
        "properties": {
          "terminal_decline": {
            "type": "number",
            "description": "Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.",
            "minimum": 0.01,
            "maximum": 0.2
          },
          "b_min": {
            "type": "number",
            "description": "Lowest hyperbolic b the fit may use; below b_max.",
            "minimum": 0,
            "maximum": 2.5
          },
          "b_max": {
            "type": "number",
            "description": "Highest hyperbolic b the fit may use; above b_min.",
            "minimum": 0,
            "maximum": 2.5
          }
        },
        "additionalProperties": false
      },
      "EurTotal": {
        "type": "object",
        "description": "A stream's EUR over the plan.",
        "required": [
          "value",
          "days",
          "wells"
        ],
        "properties": {
          "value": {
            "type": [
              "number",
              "null"
            ],
            "description": "EUR summed over the wells with one; null when none has."
          },
          "days": {
            "type": [
              "integer",
              "null"
            ],
            "description": "ip_day of the EUR; null when none has one, or when the wells summed differ in eur_years: the sum then runs to no one day, and each scenario is read apart."
          },
          "wells": {
            "type": "integer",
            "description": "Wells with an EUR."
          },
          "p10": {
            "$ref": "#/components/schemas/BandEurTotal",
            "description": "With band_eur: true, the P10 band's EUR over the plan."
          },
          "p90": {
            "$ref": "#/components/schemas/BandEurTotal",
            "description": "With band_eur: true, the P90 band's EUR over the plan."
          }
        },
        "additionalProperties": false
      },
      "DatasetEur": {
        "type": "object",
        "description": "EUR on this server.",
        "required": [
          "available",
          "method",
          "defaults",
          "bounds",
          "streams",
          "versions"
        ],
        "properties": {
          "available": {
            "type": "boolean",
            "description": "Whether this server fits EUR (the forecast worker can run Novi's decline fit); eur: true answers 503 when false."
          },
          "method": {
            "type": [
              "string",
              "null"
            ],
            "description": "Novi's type-curve decline fit; null when unavailable."
          },
          "defaults": {
            "$ref": "#/components/schemas/Decline"
          },
          "bounds": {
            "type": "object",
            "description": "Allowed ranges, inclusive; b_min must also be below b_max.",
            "required": [
              "eur_years",
              "terminal_decline",
              "b_min",
              "b_max"
            ],
            "properties": {
              "eur_years": {
                "type": "object",
                "description": "eur_years range.",
                "required": [
                  "min",
                  "max"
                ],
                "properties": {
                  "min": {
                    "type": "number",
                    "description": "Lowest allowed."
                  },
                  "max": {
                    "type": "number",
                    "description": "Highest allowed."
                  }
                },
                "additionalProperties": false
              },
              "terminal_decline": {
                "type": "object",
                "description": "terminal_decline range.",
                "required": [
                  "min",
                  "max"
                ],
                "properties": {
                  "min": {
                    "type": "number",
                    "description": "Lowest allowed."
                  },
                  "max": {
                    "type": "number",
                    "description": "Highest allowed."
                  }
                },
                "additionalProperties": false
              },
              "b_min": {
                "type": "object",
                "description": "b_min range.",
                "required": [
                  "min",
                  "max"
                ],
                "properties": {
                  "min": {
                    "type": "number",
                    "description": "Lowest allowed."
                  },
                  "max": {
                    "type": "number",
                    "description": "Highest allowed."
                  }
                },
                "additionalProperties": false
              },
              "b_max": {
                "type": "object",
                "description": "b_max range.",
                "required": [
                  "min",
                  "max"
                ],
                "properties": {
                  "min": {
                    "type": "number",
                    "description": "Lowest allowed."
                  },
                  "max": {
                    "type": "number",
                    "description": "Highest allowed."
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "streams": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Stream.",
              "enum": [
                "oil",
                "gas"
              ]
            },
            "description": "Streams that get an EUR."
          },
          "versions": {
            "type": [
              "object",
              "null"
            ],
            "description": "Library versions the forecast worker fits with, by package name; null on the sample stack.",
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "additionalProperties": false
      },
      "DeclineSeries": {
        "type": "object",
        "description": "One stream's cumulative curve.",
        "required": [
          "key",
          "ip_days",
          "values"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "Your key for the curve; results come back in request order with it.",
            "minLength": 1,
            "maxLength": 200
          },
          "ip_days": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "Days since first production.",
              "minimum": 1,
              "maximum": 18250
            },
            "description": "ip_days, ascending, as a forecast returns them (send every ip_day: the fit uses the whole curve).",
            "minItems": 3,
            "maxItems": 400
          },
          "values": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "Cumulative volume at the matching ip_day, 0 or more; a negative one is a 400."
            },
            "description": "Cumulative volumes, one per ip_day.",
            "minItems": 3,
            "maxItems": 400
          },
          "stream": {
            "type": "string",
            "description": "The curve's stream, fit with its settings; required when decline sets per-stream settings.",
            "enum": [
              "oil",
              "gas"
            ]
          }
        },
        "additionalProperties": false
      },
      "DeclinesRequest": {
        "type": "object",
        "description": "Curves and settings.",
        "required": [
          "series"
        ],
        "properties": {
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeclineSeries"
            },
            "description": "Curves to fit, 1 to 500.",
            "minItems": 1,
            "maxItems": 500
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings"
          }
        },
        "additionalProperties": false
      },
      "DeclinesResponse": {
        "type": "object",
        "description": "EUR per curve.",
        "required": [
          "decline",
          "results"
        ],
        "properties": {
          "decline": {
            "$ref": "#/components/schemas/Decline"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One series' EUR.",
              "required": [
                "key",
                "eur"
              ],
              "properties": {
                "key": {
                  "type": "string",
                  "description": "The series key."
                },
                "eur": {
                  "$ref": "#/components/schemas/Eur"
                }
              },
              "additionalProperties": false
            },
            "description": "One per series, in request order."
          }
        },
        "additionalProperties": false
      },
      "ForecastRequest": {
        "type": "object",
        "description": "Forecast request.",
        "required": [],
        "properties": {
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WellInput"
            },
            "description": "Drawn wells (required unless `layout` is sent).",
            "minItems": 1,
            "maxItems": 50
          },
          "layout": {
            "$ref": "#/components/schemas/LayoutSource",
            "description": "Instead of wells: a fill boundary the server lays 1 to 50 wells out in."
          },
          "designs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignInput"
            },
            "description": "Completion designs; every well is forecast with each. Leave out for one design at the recent-completions median. A well's own completions, a scenario's and a pad's or layout's need one design.",
            "minItems": 1,
            "maxItems": 25
          },
          "scenarios": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScenarioInput"
            },
            "description": "Values for each scenario's wells, keyed by the `scenario` the wells name; a scenario without an entry takes the request's values.\n\nA well's own completions, `til_date` and landing beat its scenario's, as do its pad's and its layout's or bench's. A scenario's completions beat the design's, and its `til_date` and `pdp` the request's. Once an entry sets completions, every well's `inputs.resolved` gives them. Once one sets a TIL date or landing that a well takes, `inputs.resolved` gives each well's `til_date` and `landing`, and the export's wells table adds `til_date`, `til_layer` and `landing_layer`.\n\nA 400 naming the entry refuses a name no well has, a repeated name, `scenarios` when no well has a scenario, and completions in it under more than one design.",
            "minItems": 1,
            "maxItems": 10
          },
          "pads": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PadInput"
            },
            "description": "Values for each pad's wells, keyed by the `pad` the wells name; a well on no listed pad takes the layers below. An entry may hold only `pad` and `name`.\n\nA well's own completions, `til_date` and landing beat its pad's, an entry's `formations` beat its own values, and a pad beats its wells' scenarios. Once an entry sets completions, every well's `inputs.resolved` gives them. Once one sets a TIL date or landing that a well takes, `inputs.resolved` gives each well's `til_date` and `landing`, and the export's wells table adds `til_date`, `til_layer` and `landing_layer`.\n\nA 400 naming the field refuses:\n\n- a pad no well has, or a repeat (1 and \"1\" are one pad);\n- a bad `pad` on any well;\n- over 200,000 `formations` entries across the list;\n- `pads` with `layout` or `layouts`, whose own fields set their wells;\n- a well with no formation that takes `landing_below_top_ft` or `landing_fraction` from an entry's own values;\n- completions in it under more than one design.",
            "minItems": 1
          },
          "formations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormationLandingInput"
            },
            "description": "The request's landing per formation, each formation at most once; a landing on the well, its pad, layout, bench or scenario entry beats it. Goes with `wells` or `layout`.\n\nAn entry for a formation no well has is accepted. Completions per formation stay in `designs`. Once an entry sets a landing that a well takes, `inputs.resolved` gives each well's `til_date` and `landing`, and the export's wells table adds `til_date`, `til_layer` and `landing_layer`.",
            "maxItems": 100
          },
          "pdp": {
            "type": "boolean",
            "default": true,
            "description": "Space against existing (PDP) wells; false spaces drawn wells against each other only. A scenario's `pdp` in `scenarios` beats it."
          },
          "explain": {
            "type": "boolean",
            "default": false,
            "description": "Add each well's explanations per design (up to 10 wells × designs). Not with summary."
          },
          "explain_top": {
            "type": "integer",
            "description": "With explain: true (400 without it): how many features per SHAP row and contributing wells to keep: the largest features (by absolute contribution) and heaviest wells. Default: all features, 25 wells.\n\nThe features cut are summed into one `(other)` entry (never a feature name; left out when nothing is cut), and the wells cut add to `other_weight`. A row's contributions still sum to the uncut row's (null contributions are left out), and the response keeps its shape with fewer entries; with residual, each row's `forecast` and `residual` are the uncut row's.",
            "minimum": 1,
            "maximum": 50
          },
          "explain_ip_day": {
            "type": "integer",
            "description": "With explain: true (400 without it): each explanation, its comparisons and its analog spread keep only this ip_day's SHAP row per stream. Absent: every ip_day.\n\n- One of GET /dataset `ip_days`, checked before the models run (400 otherwise, with them in `details.allowed`).\n- As `ip_day` on GET /plans/{id}/wells/{index}/explanations/{design}.\n- `contributing_wells` and `other_weight` don't change, and a design with no forecast to explain keeps its `error`.\n- With `explain_top`, the row is picked first and then cut.",
            "minimum": 1
          },
          "ip_days": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "An ip_day from GET /dataset ip_days."
            },
            "description": "The ip_days to return, up to 36 different ones of GET /dataset ip_days (duplicates count once): every stream holds only these, ascending and once each. Absent: every ip_day.\n\nIt trims neither checks nor explanations, which cover every ip_day unless `explain_ip_day` picks one. A forecast cut so that it starts after 30 or skips an ip_day can't be priced as POST /economics `curves` (a 400): leave `ip_days` out, or send POST /economics `forecast`.",
            "minItems": 1
          },
          "summary": {
            "type": "boolean",
            "default": false,
            "description": "Return each well as a plan summary (PlanWellSummary): forecasts and neighbor count, without features, subsurface values, the neighbor list or explanations. Not with explain."
          },
          "eur": {
            "type": "boolean",
            "default": false,
            "description": "Add the EUR (Novi type-curve decline fit) to each oil and gas forecast; GET /dataset eur says whether this server has it (503 if not)."
          },
          "eur_water": {
            "type": "boolean",
            "default": false,
            "description": "Fit water's EUR too, with `decline.water` over the settings at any layer.\n\nAdds `eur` to each water forecast, `water` to the `decline` echo, `totals[].eur` and `inputs.resolved.decline`, and water's columns to the eur, forecast and wells tables, where monthly water runs to the EUR day. BOE never reads it, and oil's and gas's fits are unchanged. Without it, `decline.water` is a 400. Needs `eur: true` (a 400 on eur_water without it)."
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings",
            "description": "Decline fit settings, with eur: true only; any left out take Novi's defaults (GET /dataset eur.defaults), and oil and gas (with eur_water, water) override them per stream. The plan layer: a well, pad, layout, bench, scenario or `formations` entry can set its wells' own, field by field."
          },
          "til_date": {
            "type": "string",
            "description": "TIL (first production) date, YYYY-MM-DD, for every well no narrower layer dates: from GET /dataset as_of to 30 years from today. Echoed in each such well's inputs.",
            "format": "date"
          },
          "bands": {
            "type": "boolean",
            "default": false,
            "description": "Add P10/P90 bands to each stream forecast (Novi's predrill bands, same model call); GET /dataset bands says which streams have them, and a request answers 503 when none has."
          },
          "band_eur": {
            "type": "boolean",
            "default": false,
            "description": "Also fit each oil and gas band to an EUR with the decline settings, and water's with eur_water: two more decline fits per such forecast (about three times eur's fitting). Needs bands and eur."
          },
          "eur_curve": {
            "type": "string",
            "description": "With eur: true (400 without it): add each oil and gas EUR's curve (and water's with `eur_water`), `eur.curve`.\n\nThe curve: cumulative volumes to the EUR's `days`.\n\nIt continues the forecast from its last ip_day on the same decline fit: `month` every 30 days (the export's monthly cumulatives), `year` every 360 days plus the EUR's day. A decline-curve extension, not a model output.\n\n- With bands and band_eur, each band's EUR gets its curve too.\n- With `ip_days`, the curve still starts after the forecast's last ip_day before the filter, as the EUR is fit on the whole curve.\n- At most 25 forecasts (wells × designs) with `month` and 100 with `year`; 400 above, with `details.max` and `details.count` (a plan's wells take eur_curve one at a time).",
            "enum": [
              "month",
              "year"
            ]
          },
          "explain_compare": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A reference.",
              "enum": [
                "formation",
                "dataset",
                "analogs"
              ]
            },
            "description": "With explain: true (400 without it): the references each explanation is compared with, as `compare` on GET /plans/{id}/wells/{index}/explanations/{design}.\n\nEach explained stream gains `comparisons`, one per reference.\n\n`formation` is the wells the model explained in this well's formation (a typical Wolfcamp A well, say), `dataset` every well it explained. At each ip_day, `values` holds, by feature, this well's SHAP contribution minus the reference wells' mean: read an entry as \"compared with a typical Wolfcamp A well, this input adds (or removes) N\". It rearranges the same SHAP values, so it can't contradict them.\n\n- `value` is the reference wells' mean `expected_value` plus their mean contributions (`start_from` `reference`), or this well's own `expected_value` plus theirs where no mean is stored (`start_from` `well`).\n- `(baseline)` in `values` is this well's `expected_value` less the reference mean: mostly its lateral length against theirs, in models that scale by lateral. It comes only with `start_from` `reference`, not when it rounds to 0, and never counts toward `top` or `(other)`.\n- `value` plus `values` is this well's `expected_value` plus its SHAP values (each rounded to 0.001); the SHAP row's `residual` is what they leave out of the forecast.\n- `wells` counts the reference at that ip_day (long ip_days rest on older wells); under 5, `value` is null, `values` empty and `start_from` absent.\n- `top` folds small differences into `(other)`; `ip_day` keeps one row. A reference without a baseline (a formation the model never saw) is `{reference, error}`; GET /models/{model_num}/baselines lists them.\n\n`analogs`, on model sets that store their analogs' SHAP, averages this forecast's own first 15 analogs per stream the same way (a missing feature counts 0), in the analogs list's ranking (reweighed by `analog_weights` when sent), whether or not `analogs` is asked; `analogs` itself comes only when asked. Its `keys` name them, nearest first. It is `{reference, error}` when the dataset has no analog index, the set stores no analog SHAP or it can't be read (tried again after a minute), the analogs can't be ranked, or the model has no training analogs of this forecast in its formation.",
            "minItems": 1,
            "maxItems": 3,
            "uniqueItems": true
          },
          "explain_spread": {
            "type": "boolean",
            "default": false,
            "description": "With explain: true (400 without it): add each explained stream's `analog_spread`.\n\nAn analog spread, not the model's uncertainty: for the model's own P10/P90, send `bands: true`.\n\nIt is the 10th, 50th and 90th percentiles (q10 the low end) of what the model's 50 heaviest contributing training wells actually produced by each ip_day, each scaled to this well's lateral length (wells without one are left out). Only wells whose production reached the ip_day count (`wells`); under 5, the quantiles are null. `contributing_wells` still lists 25, or `top` when that is fewer, and `other_weight` is re-summed from 50 weights, so it can differ in the last digit.\n\n`forecast` says whether the served forecast (as GET /plans/{id}/wells/{index} serves it; on POST /forecasts, `forecasts[d]` before `ip_days` cuts it) is below, within or above q10 to q90, compared before rounding; null without quantiles or a served value. `driver` names the input that moves it there."
          },
          "explain_analogs": {
            "type": "boolean",
            "default": false,
            "description": "With explain: true (400 without it): add each explained stream's `analogs`.\n\nThe model's own analog wells for this forecast, from its training wells, each stream from its own model.\n\nThey are the 50 nearest wells of the same formation and parent/child status whose lateral is within 25% of this well's (widened to 50%, then 100%, until 5 pass), by distance over the model's inputs at its last ip_day, standard-scored and weighted by mean |SHAP| (`weights`). `wells` lists them nearest first, whatever `top`.\n\n`spread` is the 10th, 50th and 90th percentiles of what they produced by ip_day, scaled to this well's lateral, as `analog_spread`: an analog spread, not the model's uncertainty. Unless `coverage` passes, it is `{error}` with the measured figure (the wells are still listed): on the model's held-out wells, q10 to q90 must have held 70% to 90% of actual production at `coverage.ip_day` (nominal 80%) over at least 300 wells. `coverage.measured` is always given.\n\nTheir type curve: POST /wells/typecurve with their keys as `wells`, `normalize_lateral_ft` = `spread.lateral_length_ft` and `quantiles: [10, 50, 90]` matches `spread` while that lateral is within 100 to 20,000 ft.\n\nA dataset without an analog index (the default dataset), or a set before its index is installed, answers `analogs: {error}` with the reason; `analog_spread` is unchanged."
          },
          "explain_inputs": {
            "type": "boolean",
            "default": false,
            "description": "With explain: true (400 without it): add `inputs` to each SHAP row, the value of each feature its `values` lists as the model read it, as `inputs` on GET /plans/{id}/wells/{index}/explanations/{design} does."
          },
          "explain_residual": {
            "type": "boolean",
            "default": false,
            "description": "With explain: true (400 without it): adds `forecast` and `residual` to each SHAP row; show the residual beside the drivers (\"not attributed\") so the parts add up to the forecast.\n\n`forecast` is the forecast served at that ip_day for this design, as GET /plans/{id}/wells/{index} serves it (on POST /forecasts, `forecasts[d]` before `ip_days` cuts it), or null. `residual` = `forecast` − `expected_value` − the sum of `values`, unrounded, on the uncut row, so `top` and `ip_day` don't change it; null when either is null. On a causal model set (GET /model-sets?include=model_type) SHAP values approximate the treatment effect, so the residual can be large. As `residual=true` on GET /plans/{id}/wells/{index}/explanations/{design}."
          },
          "explain_driver": {
            "type": "boolean",
            "default": false,
            "description": "With explain: true and explain_spread or explain_analogs (400 without them): adds `driver` to every analog spread row: the model input that moves this forecast furthest the way the row's `forecast` flag points.\n\nIt is `{feature, value, reference}`: with `below`, the most negative contribution; with `above`, the most positive; in the stream's unit to 0.001, from the uncut SHAP row. With `reference` `formation`, a contribution is this well's SHAP value minus the typical well's of its formation at that ip_day (the `compare=formation` baseline, when it has at least 5 wells there; a missing feature counts 0); otherwise `model`, the raw SHAP value. Null when the flag is `within` or null, or no input moves it that way (a contribution rounding to 0 counts as none). `comparisons` still come only with `compare`. As `driver=true` on GET /plans/{id}/wells/{index}/explanations/{design}."
          },
          "explain_weight_counts": {
            "type": "boolean",
            "default": false,
            "description": "With explain: true (400 without it): adds `weighted_wells` and `effective_wells` to each explained stream: how many training wells carry weight, and how concentrated it is.\n\nThey count every training well, not only those `contributing_wells` lists: check them before saying a forecast rests on the listed wells. Both are null, with `weights_error`, for a fit without tree weights or counts; all-zero weights give `weighted_wells` 0 and `effective_wells` null. As `weight_counts=true` on GET /plans/{id}/wells/{index}/explanations/{design}."
          },
          "explain_analogs_detail": {
            "type": "boolean",
            "default": false,
            "description": "With explain_analogs: true (400 without it), as `analogs_detail` on GET /plans/{id}/wells/{index}/explanations/{design} does: adds each analog's production, EURs and model inputs to `analogs.wells`.\n\n- `cum_oil_360`, `cum_oil_720`, `cum_oil_1080`, `cum_gas_360`, `cum_gas_720`, `cum_gas_1080`: actual cumulative oil and gas (bbl, mcf) at 1, 2 and 3 years of 30-day months, unscaled; null where it hasn't produced that long. `cum_oil_life`, `cum_gas_life`: to date.\n- `eur_oil`, `eur_gas`: EUR (bbl, mcf) from Novi's type-curve decline fit, as `eur: true` runs it, on its actual cumulative at every 30-day ip_day (its last 400), unscaled.\n- `inputs`: the model's raw inputs for it at the distance's ip_day (`basis`), in `weights` order, null where missing.\n\nAn EUR is null when the fit fails, without production at every 30-day ip_day from 30 to 360, with a history longer than `eur_years`, or below the cumulative to date. One not above its last 30-day cumulative is a flat extension, kept only for an analog without production in its last 90 days (Novi's dry-well rule). An EUR from under 3 years of production (a null `cum_oil_1080` or `cum_gas_1080`) is less certain.\n\n`analogs.inputs` gives this forecast's own inputs the same way. `analogs.eur` gives the `basis`, the `decline` settings and how many got each EUR (`fitted`); it is `{error}` when the server has no EUR or the fit failed or took over 30 s. The settings are each well's own once a layer below the plan reaches any well with a setting other than `water`; else the plan's (made with `eur: true`), the forecast's `decline`, or GET /dataset `eur.defaults`.\n\nEach analog is fit once per request; the worker keeps recent fits, so a repeat is cheaper. Nothing else in the answer changes."
          },
          "explain_analog_weights": {
            "type": "object",
            "additionalProperties": {
              "type": "number",
              "minimum": 0
            },
            "minProperties": 1,
            "description": "With explain_analogs: true (400 without it): your weight per model input, as `{\"novi_lateral_length\": 0.4, \"novi_tvd\": 0}`, checked before the models run.\n\nAs `analog_weights` on GET /plans/{id}/wells/{index}/explanations/{design} takes them.\n\nYour weights for the analog distance, as shares on the scale of `analogs.weights[].weight`, one map for every stream's model. A named input takes exactly its share and the model's other inputs split the rest as the model weighs them; when nothing takes the rest, the shares sent are rescaled to sum to 1. A model with none of the names answers as without them.\n\nWeights are finite, from 0 (which drops an input), summing to 1 at most. A 400: a name no model in the set takes (`details.allowed` lists their inputs), a malformed pair, a repeated name, a negative or non-finite weight, or a sum over 1. Weights that all come to 0, or weighted inputs that don't vary across the candidates, answer `analogs: {error}`.\n\nA reweighted stream gives `analogs.analog_weights` (yours), `weights` (the distance's, heaviest first, each with its `model_weight`) and `basis`, naming the inputs you weighted; `method` stays `shap_weighted`. Its `spread` is `{error}` unless it lists the wells the model's weights list, since `coverage` (still given) was measured with those. The filters don't change; `analogs_detail` and `format=csv` follow the reweighted analogs. Without an analog index, names aren't checked."
          },
          "totals": {
            "type": "boolean",
            "default": false,
            "description": "Add `totals`: one per design (with scenarios, per scenario and design), as GET /plans/{id} totals these wells. Absent or false: no `totals` key.\n\n- Summed on the full forecasts, so `eur` and `by_date` ignore `ip_days`; each stream (and with boe its BOE) is then cut to `ip_days` as the wells are.\n- `by_date` comes when the request sends `til_date` or any well has its own; a well without one is TIL today (UTC).\n- Goes with summary, explain, layout, scenarios, eur, bands and band_eur."
          },
          "boe": {
            "type": "boolean",
            "default": false,
            "description": "Add `boe` beside `oil`, `gas` and `water` in every forecast that has streams, and with totals in `totals[].forecast`; with band_eur, `totals[].eur.boe` adds `p10` and `p90`. Absent or false: no `boe` key anywhere.\n\nBOE is oil plus gas / 6 (6 mcf per bbl), on ip_days where both have a value; on a set serving one of them the other counts 0, and serving neither, BOE is 0.\n\nIts P10 adds oil's P10 and gas's P10 / 6 (P90 likewise). The models predict each stream apart, so this isn't the P10 of BOE itself; it is as wide as BOE's would be if oil and gas moved together. Novi's P10 is the low case. Totals add the BOE of the wells that have both oil and gas forecasts, and say how many in `wells`."
          },
          "async": {
            "type": "boolean",
            "default": false,
            "description": "Run it as a job: the body is checked as without it (the same 400s), then the answer is 202 with a ForecastJob and its `Location`. GET /forecasts/{id}?wait=25 until `status` is `done` or `error`; `result` is then the body this request would have answered with. Takes `Idempotency-Key`."
          }
        },
        "additionalProperties": false
      },
      "ForecastJob": {
        "type": "object",
        "description": "An async forecast.",
        "required": [
          "id",
          "status",
          "created_at",
          "finished_at",
          "seconds",
          "result",
          "error",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Forecast job id.",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "description": "running, then done or error.",
            "enum": [
              "running",
              "done",
              "error"
            ]
          },
          "created_at": {
            "type": "string",
            "description": "When it was requested.",
            "format": "date-time"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When it finished or failed.",
            "format": "date-time"
          },
          "seconds": {
            "type": "number",
            "description": "Run time so far, or in total once finished."
          },
          "result": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ForecastResponse"
              },
              {
                "type": "null"
              }
            ],
            "description": "Once done, the body POST /forecasts answers with without `async`; null otherwise."
          },
          "error": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ErrorBody"
              },
              {
                "type": "null"
              }
            ],
            "description": "Once failed, the error POST /forecasts would have answered with (a 500's message, `internal error`, names no request id); null otherwise."
          },
          "links": {
            "type": "object",
            "description": "Related URLs.",
            "required": [
              "self"
            ],
            "properties": {
              "self": {
                "type": "string",
                "description": "This job."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "ForecastWell": {
        "type": "object",
        "description": "A forecast well.",
        "required": [
          "index",
          "key",
          "label",
          "inputs",
          "lateral_length_ft",
          "estimates",
          "forecasts",
          "spacing",
          "features",
          "subsurface"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "Position of the well in the request.",
            "minimum": 0
          },
          "key": {
            "type": "string",
            "description": "Key the models use for the well, as DRAWN-<index>; other drawn wells appear among neighbors by this key."
          },
          "label": {
            "type": "string",
            "description": "Display name: Plan well N in a plan, Drawn well N from POST /forecasts, counting from 1."
          },
          "inputs": {
            "$ref": "#/components/schemas/WellInputEcho"
          },
          "lateral_length_ft": {
            "type": "integer",
            "description": "The lateral length the model got, ft, rounded: the well's `typed_lateral` length when it applies, else from the heel when the well has one, else shl, to bhl."
          },
          "estimates": {
            "$ref": "#/components/schemas/DesignEstimates"
          },
          "forecasts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignForecast"
            },
            "description": "One forecast per design, in design order."
          },
          "lateral_length_source": {
            "type": "string",
            "description": "Only on a well sent a `typed_lateral`: typed when the well uses its length_ft, measured when it uses the length between the ends instead.",
            "enum": [
              "typed",
              "measured"
            ]
          },
          "name": {
            "type": "string",
            "description": "The name the request gave the well, trimmed; only when it gave one. `label` doesn't change."
          },
          "spacing": {
            "type": "object",
            "description": "Spacing.",
            "required": [
              "node",
              "neighbors"
            ],
            "properties": {
              "node": {
                "$ref": "#/components/schemas/DesignNode"
              },
              "neighbors": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SpacingNeighbor"
                },
                "description": "Neighbors, closest first."
              }
            },
            "additionalProperties": false
          },
          "features": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FeatureValues"
              },
              {
                "type": "null"
              }
            ],
            "description": "Spacing features at ip_day 1."
          },
          "subsurface": {
            "type": "object",
            "description": "Subsurface values at the well (empty without a formation).",
            "additionalProperties": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "explanations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Explanation"
            },
            "description": "With explain: true, one per design, in design order."
          },
          "scored_inputs": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One design's scored inputs.",
              "required": [
                "design",
                "ip_day",
                "values"
              ],
              "properties": {
                "design": {
                  "type": "integer",
                  "description": "The design's position in the plan's `designs`, from 0."
                },
                "ip_day": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "The first model row's ip_day, the day `values` is at. Null with no model rows."
                },
                "values": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "description": "Each model input's value in that row, by feature name, in API units. Null with no model rows. A null inside means the input had no number or text in that row.",
                  "additionalProperties": {
                    "type": [
                      "number",
                      "string",
                      "null"
                    ]
                  }
                }
              },
              "additionalProperties": false
            },
            "description": "Only with include=scored_inputs on GET /plans/{id}/wells/{index}, never on POST /forecasts: what the models scored, one entry per design, in design order; a design with no model rows has nulls.\n\n- Unlike `features` (the spacing features at ip_day 1), these are the inputs at a day the models score, with each design's completions. Other days' values: `GET /plans/{id}/wells/{index}/explanations/{design}?inputs=true`, for the inputs that day's SHAP row lists.\n- On a set with several models, the first served stream's model's rows (oil, else gas, else water)."
          }
        },
        "additionalProperties": false
      },
      "ForecastResponse": {
        "type": "object",
        "description": "Forecasts.",
        "required": [
          "pdp",
          "designs",
          "wells",
          "timings"
        ],
        "properties": {
          "pdp": {
            "type": "boolean",
            "description": "Whether existing wells were in spacing."
          },
          "designs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Design"
            },
            "description": "The completion designs, as run."
          },
          "scenarios": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScenarioEcho"
            },
            "description": "When the request sent scenarios: each, in the order its first well came, with its well count."
          },
          "layout": {
            "$ref": "#/components/schemas/LayoutEcho",
            "description": "When the request sent layout: what was laid out."
          },
          "decline": {
            "$ref": "#/components/schemas/Decline",
            "description": "With eur: true, the request's decline settings, which a well may override (`per_well`)."
          },
          "bands": {
            "$ref": "#/components/schemas/BandsEcho",
            "description": "With bands: true, the bands every forecast carries."
          },
          "wells": {
            "description": "Wells, in request order; with summary: true, as plan summaries.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/ForecastWells"
              },
              {
                "$ref": "#/components/schemas/ForecastWellSummaries"
              }
            ]
          },
          "totals": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanTotals"
            },
            "description": "With totals: true: one per design, or per scenario and design, as GET /plans/{id} gives them for the same wells."
          },
          "timings": {
            "type": "object",
            "description": "Step times, ms. A forecast whose wells, designs, pdp, til dates, EUR settings and bands match a request running now, or one answered earlier today (UTC) and still kept, shows 0 for the steps it didn't run; `explain`, `explain_top`, `ip_days`, `summary`, `band_eur`, `totals` and `boe` don't matter. Its total is its own.",
            "required": [
              "estimate",
              "subsurface",
              "spacing",
              "calc",
              "forecast",
              "details",
              "total"
            ],
            "properties": {
              "estimate": {
                "type": "integer",
                "description": "TVD estimates."
              },
              "subsurface": {
                "type": "integer",
                "description": "Subsurface interpolation."
              },
              "spacing": {
                "type": "integer",
                "description": "Spacing worker."
              },
              "calc": {
                "type": "integer",
                "description": "Spacing feature worker."
              },
              "forecast": {
                "type": "integer",
                "description": "Oil, gas and water models, every design."
              },
              "details": {
                "type": "integer",
                "description": "Neighbor details."
              },
              "explain": {
                "type": "integer",
                "description": "Explanations, with explain: true."
              },
              "total": {
                "type": "integer",
                "description": "Whole request."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "ForecastWells": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/ForecastWell"
        },
        "description": "Forecast wells.",
        "minItems": 1
      },
      "ForecastWellSummaries": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/PlanWellSummary"
        },
        "description": "With summary: true, plan summaries.",
        "minItems": 1
      },
      "PlanRequest": {
        "type": "object",
        "description": "Plan request.",
        "required": [],
        "properties": {
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WellInput"
            },
            "description": "Plan wells (required unless `layout` or `layouts` is sent); up to the server's GET /dataset `limits.plan_wells` (10,000 by default, at most 100,000) divided by the number of designs.",
            "minItems": 1,
            "maxItems": 100000
          },
          "layout": {
            "$ref": "#/components/schemas/LayoutSource",
            "description": "Instead of wells: a fill boundary the server lays the plan's wells out in, up to GET /dataset `limits.plan_wells` divided by the number of designs and at most 10,000, a fill's own limit."
          },
          "layouts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanLayoutSource"
            },
            "description": "Instead of wells or layout: layouts whose wells the plan takes one after another, up to GET /dataset `limits.plan_wells` divided by the number of designs in all, each at most 10,000 (a fill's own limit).\n\n- All layouts share one work limit (about a second). Each evens out as POST /layouts/fill does, with the work the plan's fills leave, unless any layout has a bench with a non-zero offset_ft: then none does, so a stagger set across layouts holds.\n- Errors name layouts[i]. Past the plan's wells in all: a 400 on layouts[i] with details.max (the plan's wells), details.before (wells the layouts before it laid out) and details.count (its own).",
            "minItems": 1,
            "maxItems": 100
          },
          "designs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignInput"
            },
            "description": "Completion designs; every well is forecast with each. Leave out for one design at the recent-completions median. A well's own completions, a scenario's and a pad's or layout's need one design.",
            "minItems": 1,
            "maxItems": 10
          },
          "scenarios": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScenarioInput"
            },
            "description": "Values for each scenario's wells, keyed by the `scenario` the wells name; a scenario without an entry takes the request's values.\n\nA well's own completions, `til_date` and landing beat its scenario's, as do its pad's and its layout's or bench's. A scenario's completions beat the design's, and its `til_date` and `pdp` the request's. Once an entry sets completions, every well's `inputs.resolved` gives them. Once one sets a TIL date or landing that a well takes, `inputs.resolved` gives each well's `til_date` and `landing`, and the export's wells table adds `til_date`, `til_layer` and `landing_layer`.\n\nA 400 naming the entry refuses a name no well has, a repeated name, `scenarios` when no well has a scenario, and completions in it under more than one design.",
            "minItems": 1,
            "maxItems": 20
          },
          "pads": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PadInput"
            },
            "description": "Values for each pad's wells, keyed by the `pad` the wells name; a well on no listed pad takes the layers below. An entry may hold only `pad` and `name`.\n\nA well's own completions, `til_date` and landing beat its pad's, an entry's `formations` beat its own values, and a pad beats its wells' scenarios. Once an entry sets completions, every well's `inputs.resolved` gives them. Once one sets a TIL date or landing that a well takes, `inputs.resolved` gives each well's `til_date` and `landing`, and the export's wells table adds `til_date`, `til_layer` and `landing_layer`.\n\nA 400 naming the field refuses:\n\n- a pad no well has, or a repeat (1 and \"1\" are one pad);\n- a bad `pad` on any well;\n- over 200,000 `formations` entries across the list;\n- `pads` with `layout` or `layouts`, whose own fields set their wells;\n- a well with no formation that takes `landing_below_top_ft` or `landing_fraction` from an entry's own values;\n- completions in it under more than one design.",
            "minItems": 1
          },
          "formations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormationLandingInput"
            },
            "description": "The request's landing per formation, each formation at most once; a landing on the well, its pad, layout, bench or scenario entry beats it. Goes with `wells`, `layout` or `layouts`.\n\nAn entry for a formation no well has is accepted. Completions per formation stay in `designs`. Once an entry sets a landing that a well takes, `inputs.resolved` gives each well's `til_date` and `landing`, and the export's wells table adds `til_date`, `til_layer` and `landing_layer`.",
            "maxItems": 100
          },
          "pdp": {
            "type": "boolean",
            "default": true,
            "description": "Space against existing (PDP) wells. A scenario's `pdp` in `scenarios` beats it, and this stays the plan's echoed `pdp`."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your name for the plan.",
            "maxLength": 100
          },
          "eur": {
            "type": "boolean",
            "default": false,
            "description": "Add the EUR (Novi type-curve decline fit) to each oil and gas forecast; GET /dataset eur says whether this server has it (503 if not)."
          },
          "eur_water": {
            "type": "boolean",
            "default": false,
            "description": "Fit water's EUR too, with `decline.water` over the settings at any layer.\n\nAdds `eur` to each water forecast, `water` to the `decline` echo, `totals[].eur` and `inputs.resolved.decline`, and water's columns to the eur, forecast and wells tables, where monthly water runs to the EUR day. BOE never reads it, and oil's and gas's fits are unchanged. Without it, `decline.water` is a 400. Needs `eur: true` (a 400 on eur_water without it)."
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings",
            "description": "Decline fit settings, with eur: true only; any left out take Novi's defaults (GET /dataset eur.defaults), and oil and gas (with eur_water, water) override them per stream. The plan layer: a well, pad, layout, bench, scenario or `formations` entry can set its wells' own, field by field."
          },
          "til_date": {
            "type": "string",
            "description": "TIL (first production) date, YYYY-MM-DD, for every well no narrower layer dates: from GET /dataset as_of to 30 years from today. Echoed in each such well's inputs.",
            "format": "date"
          },
          "bands": {
            "type": "boolean",
            "default": false,
            "description": "Add P10/P90 bands to each stream forecast (Novi's predrill bands, same model call); GET /dataset bands says which streams have them, and a request answers 503 when none has."
          },
          "band_eur": {
            "type": "boolean",
            "default": false,
            "description": "Also fit each oil and gas band to an EUR with the decline settings, and water's with eur_water: two more decline fits per such forecast (about three times eur's fitting). Needs bands and eur."
          },
          "callback_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Where to POST the plan once it is done or fails: https, to a host the server allows (GET /export-formats callbacks). See POST /plans.",
            "maxLength": 2048
          },
          "depletion_chain": {
            "type": "boolean",
            "description": "Feed each planned well's P50 production to the plan wells it is a parent of, those with a later TIL month. On by default where GET /dataset depletion_chain.available is true, else off. Only plans take it.\n\n- A well whose planned parent is TIL in an earlier calendar month is re-forecast after it, wave by wave, each design on its own parents' P50. A parent read past its 1,080-day forecast is extended with the plan's decline settings (Novi's defaults without eur).\n- Existing (PDP) parents' production is as GET /dataset depletion_chain.neighbor_production says.\n- false: a planned parent's production reads as 0 in every neighbor-production feature (novi_spacing_sum_prior_* and novi_spacing_delgados_p*), so neighbor production is existing wells' history alone.\n- With available false, the plan runs as without it, and with true sent its echo says why.\n- Each wave adds a production pass and a forecast per design, so deep chains take longer. `steps.chain` counts the waves' passes running, and a chained well finishes once its last design's wave lands."
          },
          "dry_run": {
            "type": "boolean",
            "default": false,
            "description": "With true, only check and count: the same checks as a create and a 200 with PlanDryRun, with nothing started (no job, no callback). false or absent: a plan.\n\nAn Idempotency-Key is neither kept nor replayed. Wells aren't placed, so a well whose TVD can't be estimated or whose landing can't be placed answers 200 here and fails once the plan runs (only that well with per_well_errors: true, unless no well can be placed)."
          },
          "per_well_errors": {
            "type": "boolean",
            "default": false,
            "description": "With true, a well whose TVD or landing can't be placed fails alone; the plan ends in error only when no well can be placed. Without it, one placement failure fails the whole plan.\n\n- The plan lists failed_wells. The well's summary has error {field, message}, error forecasts and no estimates or spacing; reading it or its explanations is a 409. Stats count it as missing; exports keep its reason with blank placement columns.\n- Its plan neighbors are spaced and forecast without it, as if it were never drilled: less interference, so their forecasts may read high.\n- For the like-for-like plan, run the wells again with this one placed: tvd_ft for its landing_fraction or landing_below_top_ft, and a target formation if it has none (a plan built from a layout goes as its well list, so only this well changes).\n- Economics leaves any scenario holding it unpriced (economics null, reason naming the first well without flows); list the placed wells in plan.wells to price them.\n- Worker or internal errors still fail the plan."
          },
          "from_plan": {
            "type": "string",
            "description": "Instead of wells, layout or layouts: a done plan's id. The new plan runs its stored request again on the model set's current models, and echoes `from_plan`.\n\n- It keeps the wells where they were (a layout's aren't laid out again), designs, `pdp`, decline and EUR settings, bands, depletion chain, `per_well_errors` and its start day, which undated wells take.\n- Only `name`, `callback_url` and `dry_run` go with it; any other field is a 400 naming it. A plan you can't see on this model set is 404; one running or failed is 409.\n- POST /comparisons of the two names the release and model set each ran on, so a difference comes from the models or the release, not the inputs.",
            "format": "uuid"
          },
          "assumption_set": {
            "type": "object",
            "description": "A saved assumption set: each plan field it holds that this body leaves out or sends as null is filled from it before the body is checked, unless `clear` names it; a field the body sends wins.\n\n- It fills designs, formations, til_date, pdp, depletion_chain, eur, eur_water, decline, bands and band_eur, never its pad_template or economics (not plan fields). A 400 on a filled field names it and starts \"From assumption set {name} (version {n}):\".\n- A set you can't read is 404; one made on another model set, a 400 on assumption_set naming both; without a state store, 409; with from_plan, 400.\n- The plan echoes assumption_set with the version run and the fields filled; GET /plans/{id}?include=request answers the body after the fill.\n- Without one, a plan runs on the dataset's defaults (Novi defaults) and has no assumption_set echo.",
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "An assumption set's id, from POST /saved/assumption-sets.",
                "format": "uuid"
              },
              "version": {
                "type": "integer",
                "description": "The version you read; another one is a 409 whose details.version is the current one. Left out, the current version.",
                "minimum": 1
              },
              "clear": {
                "type": [
                  "array",
                  "null"
                ],
                "description": "Set values the fill skips: til_date, eur or both. Absent, null or []: the set fills as without it.\n\n- til_date: the set's start date, so wells this body doesn't date run undated.\n- eur: the set's eur, eur_water, decline and band_eur, and each filled formations entry's decline, so the plan runs without EUR; bands and those entries' landings still fill.\n- A field this body sends still wins: a til_date sent beside it runs on that date, and \"eur\": true runs EUR on this body's own settings.\n- A name the set doesn't hold is ignored, so you needn't read the set first; a name may repeat. Any other value is a 400 on assumption_set.clear.\n- assumption_set.filled leaves out what the set didn't fill.",
                "items": {
                  "type": "string",
                  "enum": [
                    "til_date",
                    "eur"
                  ]
                }
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "PlanTotals": {
        "type": "object",
        "description": "One design's streams (one scenario's, on a plan made with scenarios), each summed over the wells with that stream (with bands: true, their P10s and P90s summed too: a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan).",
        "required": [
          "design",
          "wells_with_forecast",
          "wells_flagged",
          "forecast"
        ],
        "properties": {
          "design": {
            "type": "integer",
            "description": "The design, as its index in `designs`.",
            "minimum": 0
          },
          "scenario": {
            "type": "string",
            "description": "On a plan made with scenarios: the scenario these wells are in. Scenarios are alternatives, so no total adds two."
          },
          "wells_with_forecast": {
            "type": "integer",
            "description": "Wells with a forecast."
          },
          "wells_flagged": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Wells whose checks flagged inputs outside training; null when no well's inputs could be checked. A well whose only finding is `context` (neighbors' production outside training) isn't counted. When wells_flagged is above 0, show the flag beside any total you quote, saying how many wells it covers."
          },
          "wells_context": {
            "type": "integer",
            "description": "Wells whose checks list neighbors' production outside training in `context`, flagged or not; absent when none.",
            "minimum": 1
          },
          "forecast": {
            "$ref": "#/components/schemas/Forecast"
          },
          "eur": {
            "type": "object",
            "description": "With eur: true, each stream's EUR summed over the wells with one, and BOE over the wells with both. A v2 forecast carries the streams its model set serves (GET /model-sets `streams`), oil, gas and water on a set serving all three; a Legacy Forecast that forecast only some (Plan `streams`) carries only those.",
            "required": [
              "boe"
            ],
            "properties": {
              "oil": {
                "$ref": "#/components/schemas/EurTotal"
              },
              "gas": {
                "$ref": "#/components/schemas/EurTotal"
              },
              "water": {
                "$ref": "#/components/schemas/EurTotal",
                "description": "Only with eur_water: true. BOE doesn't read it."
              },
              "boe": {
                "type": "object",
                "description": "BOE EUR over the wells with both fits, so the sum and the well count agree.",
                "required": [
                  "value",
                  "wells"
                ],
                "properties": {
                  "value": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "Oil EUR plus gas EUR / 6 (bbl of oil equivalent) summed over the wells with both; null when none has."
                  },
                  "wells": {
                    "type": "integer",
                    "description": "Wells with both an oil and a gas EUR."
                  },
                  "p10": {
                    "$ref": "#/components/schemas/BandEurTotal",
                    "description": "With boe and band_eur: each well's P10 oil EUR plus P10 gas EUR / 6, summed over the wells with both."
                  },
                  "p90": {
                    "$ref": "#/components/schemas/BandEurTotal",
                    "description": "With boe and band_eur: each well's P90 oil EUR plus P90 gas EUR / 6, summed over the wells with both."
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "by_date": {
            "$ref": "#/components/schemas/PlanByDate",
            "description": "When any well has a TIL date, from any layer: its streams summed by calendar date."
          }
        },
        "additionalProperties": false
      },
      "PlanWellSummary": {
        "type": "object",
        "description": "A plan well's summary. With `fields`, only the asked properties are present.",
        "required": [
          "index"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "Position of the well in the request.",
            "minimum": 0
          },
          "key": {
            "type": "string",
            "description": "Key the models use for the well, as DRAWN-<index>; other drawn wells appear among neighbors by this key."
          },
          "label": {
            "type": "string",
            "description": "Display name: Plan well N in a plan, Drawn well N from POST /forecasts, counting from 1."
          },
          "inputs": {
            "$ref": "#/components/schemas/WellInputEcho"
          },
          "lateral_length_ft": {
            "type": "integer",
            "description": "The lateral length the model got, ft, rounded: the well's `typed_lateral` length when it applies, else from the heel when the well has one, else shl, to bhl."
          },
          "estimates": {
            "$ref": "#/components/schemas/DesignEstimates"
          },
          "forecasts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignForecast"
            },
            "description": "One forecast per design, in design order."
          },
          "spacing": {
            "type": "object",
            "description": "Spacing summary.",
            "required": [
              "node",
              "neighbor_count"
            ],
            "properties": {
              "node": {
                "$ref": "#/components/schemas/DesignNode"
              },
              "neighbor_count": {
                "type": "integer",
                "description": "Spacing neighbors."
              }
            },
            "additionalProperties": false
          },
          "error": {
            "type": "object",
            "description": "With per_well_errors, the placement failure.",
            "required": [
              "field",
              "message"
            ],
            "properties": {
              "field": {
                "type": "string",
                "description": "Placement field.",
                "enum": [
                  "tvd_ft",
                  "landing_below_top_ft",
                  "landing_fraction",
                  "formation"
                ]
              },
              "message": {
                "type": "string",
                "description": "Why the well could not be placed."
              }
            },
            "additionalProperties": false
          },
          "value": {
            "type": [
              "number",
              "null"
            ],
            "description": "With fields=value and sort: the sort metric's value, rounded to 0.1 in its unit; null for a well without one."
          },
          "checks": {
            "oneOf": [
              {
                "description": "Inputs the model rarely or never saw in training, or why they weren't checked.\n\nEvery ip_day's row of this design is checked against the oil model's training statistics (on a set without oil, the first served stream's model: gas, else water); the streams share features. An input is out of range only when it is more than 5% of its training 1st to 99th percentile range outside that range. Neighbors' production (parent depletion near the well) is reported in `context` instead.",
                "oneOf": [
                  {
                    "type": "object",
                    "description": "Checked inputs.",
                    "required": [
                      "available",
                      "model_num",
                      "flagged",
                      "out_of_range",
                      "missing",
                      "unknown_formation"
                    ],
                    "properties": {
                      "available": {
                        "const": true,
                        "description": "The inputs were checked."
                      },
                      "model_num": {
                        "type": "string",
                        "description": "Model whose training statistics were used: the oil model, or on a set without oil the first served stream's."
                      },
                      "flagged": {
                        "type": "boolean",
                        "description": "True when out_of_range, missing or unknown_formation reports anything; context doesn't set it. When true, show the flag beside any number you quote from this well and design."
                      },
                      "out_of_range": {
                        "type": "array",
                        "items": {
                          "$ref": "#/components/schemas/InputOutOfRange"
                        },
                        "description": "Numeric inputs outside training in any row, one per feature, in the model's feature order: say each is outside the model's training data, with its value and range.\n\nOutside means more than 5% of the training range (99th minus 1st percentile) below the 1st or above the 99th percentile of training. A feature whose two percentiles are equal has no margin. The value a feature takes for no such neighbor (days online -1, distances at the spacing defaults) isn't checked, and neighbors' production features are in `context`."
                      },
                      "context": {
                        "type": "array",
                        "items": {
                          "$ref": "#/components/schemas/InputOutOfRange"
                        },
                        "description": "Neighbors' production features (novi_spacing_sum_prior_*, novi_spacing_delgados_p*) below the 1st or above the 99th percentile of training in any row, with no margin. They don't set flagged; absent when there are none.\n\nOne per feature, in the model's feature order. They measure the parent depletion near the well: how much nearby parents have produced by its TIL, weighted by how close they are. It moves with where the lateral is drawn more than with completions, and a well drawn today near parents that have produced for years often reads above training. Say the well has more (or less) parent depletion nearby than nearly all training wells, not that an input is unusual."
                      },
                      "missing": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "description": "Model feature name."
                        },
                        "description": "Inputs blank in any row, of those blank in under 5% of training rows (inputs often blank in training aren't listed)."
                      },
                      "unknown_formation": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The target formation when the model has no training rows in it, else null."
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "description": "Inputs not checked.",
                    "required": [
                      "available",
                      "reason"
                    ],
                    "properties": {
                      "available": {
                        "const": false,
                        "description": "The inputs weren't checked."
                      },
                      "reason": {
                        "type": "string",
                        "description": "Why, as no training statistics for the model."
                      }
                    },
                    "additionalProperties": false
                  }
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Opt-in through fields=checks: the same object as forecasts[design].checks, default design 0; null when none, including failed wells. Show the flag beside any number quoted from a flagged well."
          },
          "name": {
            "type": "string",
            "description": "The name the request gave the well, trimmed; only when it gave one. `label` doesn't change. With `fields`, ask for it by name."
          },
          "nearest_same_formation_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Opt-in through fields=nearest_same_formation_ft: the smallest `minxy`, ft to 0.1, over the well's spacing neighbours in its own formation.\n\nThe neighbours are the wells, planned or existing, whose lateral midpoints are within the spacing radius of the well (GET /dataset `spacing.search_radius_ft`). Null when none is, so also when the nearest well in the formation is beyond that radius; when the well has no formation or could not be placed; and on older plans."
          },
          "lateral_length_source": {
            "type": "string",
            "description": "Only on a well sent a `typed_lateral`: typed when the well uses its length_ft, measured when it uses the length between the ends instead. With `fields`, ask for it by name.",
            "enum": [
              "typed",
              "measured"
            ]
          }
        },
        "additionalProperties": false
      },
      "PlanStorage": {
        "type": "object",
        "description": "Plan retention and sharing.",
        "required": [
          "tenant",
          "saved",
          "expires_at",
          "created_at",
          "updated_at",
          "created_by",
          "shares"
        ],
        "properties": {
          "tenant": {
            "type": "string",
            "description": "Owning tenant."
          },
          "saved": {
            "type": "boolean",
            "description": "Kept until deleted when true."
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Scratch expiry, null when saved.",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "description": "Creation time.",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "description": "Last metadata update.",
            "format": "date-time"
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "The email of the user who posted the plan, as `created_by` on saved documents. Null for older plans."
          },
          "shares": {
            "type": "integer",
            "description": "Active, unrevoked and unexpired share count.",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "UpdatePlanBody": {
        "type": "object",
        "description": "At least one change.",
        "required": [],
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "New name or null to clear.",
            "minLength": 1,
            "maxLength": 100
          },
          "saved": {
            "type": "boolean",
            "description": "Keep until deleted, or return to scratch retention."
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "UpdatedPlan": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Plan"
          },
          {
            "type": "object",
            "properties": {
              "storage": {}
            },
            "required": [
              "storage"
            ]
          }
        ],
        "description": "The plan with storage always present."
      },
      "CreatePlanShareBody": {
        "type": "object",
        "description": "Share options.",
        "required": [
          "visibility"
        ],
        "properties": {
          "visibility": {
            "type": "string",
            "description": "Intended audience, recorded with the share; it doesn't change who can read it.",
            "enum": [
              "link",
              "tenant"
            ]
          },
          "expires_in_days": {
            "type": "integer",
            "description": "Lifetime, otherwise no expiry.",
            "minimum": 1,
            "maximum": 365
          }
        },
        "additionalProperties": false
      },
      "PlanShare": {
        "type": "object",
        "description": "Share metadata without a token.",
        "required": [
          "id",
          "visibility",
          "created_at",
          "expires_at",
          "revoked_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Share id.",
            "format": "uuid"
          },
          "visibility": {
            "type": "string",
            "description": "Intended audience.",
            "enum": [
              "link",
              "tenant"
            ]
          },
          "created_at": {
            "type": "string",
            "description": "Creation time.",
            "format": "date-time"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Expiry, null for no expiry.",
            "format": "date-time"
          },
          "revoked_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Revocation time, null while unrevoked.",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "CreatedPlanShare": {
        "type": "object",
        "description": "A new share and its one-time token.",
        "required": [
          "id",
          "token",
          "visibility",
          "created_at",
          "expires_at",
          "revoked_at",
          "plan",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Share id.",
            "format": "uuid"
          },
          "token": {
            "type": "string",
            "description": "Secret token, returned only here.",
            "pattern": "^[A-Za-z0-9_-]{22}$"
          },
          "visibility": {
            "type": "string",
            "description": "Intended audience.",
            "enum": [
              "link",
              "tenant"
            ]
          },
          "created_at": {
            "type": "string",
            "description": "Creation time.",
            "format": "date-time"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Expiry, null for no expiry.",
            "format": "date-time"
          },
          "revoked_at": {
            "type": "null",
            "description": "New shares are unrevoked."
          },
          "plan": {
            "type": "object",
            "description": "Shared plan.",
            "required": [
              "id",
              "name",
              "model_set"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Plan id.",
                "format": "uuid"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Plan name."
              },
              "model_set": {
                "type": "string",
                "description": "Plan model set."
              }
            },
            "additionalProperties": false
          },
          "links": {
            "type": "object",
            "description": "Share URL.",
            "required": [
              "self"
            ],
            "properties": {
              "self": {
                "type": "string",
                "description": "Resolve this token on this API."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "PlanShareList": {
        "type": "object",
        "description": "Plan shares.",
        "required": [
          "shares"
        ],
        "properties": {
          "shares": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanShare"
            },
            "description": "Newest first, including revoked and expired shares."
          }
        },
        "additionalProperties": false
      },
      "SharedPlan": {
        "type": "object",
        "description": "Stored plan read view.",
        "required": [
          "share",
          "plan",
          "model_set"
        ],
        "properties": {
          "share": {
            "type": "object",
            "description": "Active share.",
            "required": [
              "id",
              "visibility",
              "created_at",
              "expires_at"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Share id.",
                "format": "uuid"
              },
              "visibility": {
                "type": "string",
                "description": "Intended audience.",
                "enum": [
                  "link",
                  "tenant"
                ]
              },
              "created_at": {
                "type": "string",
                "description": "Creation time.",
                "format": "date-time"
              },
              "expires_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Expiry.",
                "format": "date-time"
              }
            },
            "additionalProperties": false
          },
          "plan": {
            "$ref": "#/components/schemas/Plan"
          },
          "model_set": {
            "type": "string",
            "description": "The share own model set."
          }
        },
        "additionalProperties": false
      },
      "SavedDocBody": {
        "type": "object",
        "description": "Saved document content.",
        "required": [
          "name",
          "body"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Document name.",
            "minLength": 1,
            "maxLength": 100
          },
          "visibility": {
            "type": "string",
            "description": "Audience: private answers only its creator, tenant every user of the tenant.",
            "enum": [
              "private",
              "tenant"
            ],
            "default": "tenant"
          },
          "plan_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Attached plan UUID; omitted or null detaches.",
            "format": "uuid"
          },
          "body": {
            "type": "object",
            "additionalProperties": true,
            "description": "JSON object, at most 65,536 UTF-8 bytes; with plan_id, up to the 64 MB request body. What it holds depends on the collection.\n\n- `completion-designs`: one design as `designs[]` takes it (DesignInput), its formations unchecked against a dataset; any other body is a 400.\n- `assumption-sets`: an AssumptionSetBody, checked on each save: any other key, a value out of range or a decline without eur (top level or on a formation) is a 400 naming it (body.<field>); plan_id is a 400.\n  - A set on a model set the caller can't use isn't listed and answers 404.\n- `column-mappings`: `{ column_hints, formations? }`, checked on each save: any other key or a bad value is a 400 naming it (body.<field>).\n  - column_hints (required): as POST /inventories/read takes them.\n  - formations: maps file names to GET /formations' names, at most 100, 1 to 100 characters each, no two equal in any case once trimmed. Unchecked against a dataset: an upload skips one its model set lacks, with a warning.\n- `plan-views`: a PlanViewBody (GET /plans filters, sort and columns), each field checked as the GET /plans parameter of that name (400 naming it, body.<field>); plan_id is a 400."
          }
        },
        "additionalProperties": false
      },
      "SavedDoc": {
        "type": "object",
        "description": "Saved document.",
        "required": [
          "id",
          "collection",
          "name",
          "visibility",
          "plan_id",
          "created_at",
          "updated_at",
          "created_by",
          "etag",
          "body"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Document id.",
            "format": "uuid"
          },
          "collection": {
            "type": "string",
            "description": "Collection.",
            "enum": [
              "filter-sets",
              "completion-designs",
              "type-curves",
              "views",
              "settings",
              "assumption-sets",
              "column-mappings",
              "plan-views"
            ]
          },
          "name": {
            "type": "string",
            "description": "Name."
          },
          "visibility": {
            "type": "string",
            "description": "Recorded audience.",
            "enum": [
              "private",
              "tenant"
            ]
          },
          "plan_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Attached plan UUID.",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "description": "Creation time.",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "description": "Last update.",
            "format": "date-time"
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "The creator's email; null for older documents. A private document with none answers the whole tenant."
          },
          "etag": {
            "type": "string",
            "description": "Current ETag including quotes; send as If-Match when replacing."
          },
          "body": {
            "type": "object",
            "additionalProperties": true,
            "description": "Saved JSON content."
          },
          "version": {
            "type": "integer",
            "description": "assumption-sets only: 1 when created, one more on each PUT. POST /plans assumption_set.version names it.",
            "minimum": 1
          },
          "model_set": {
            "type": "string",
            "description": "assumption-sets only: the body's model_set, the model set the set was made on.",
            "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
          }
        },
        "additionalProperties": false
      },
      "SavedDocListItem": {
        "type": "object",
        "description": "Listed document.",
        "required": [
          "id",
          "name",
          "visibility",
          "plan_id",
          "created_at",
          "updated_at",
          "etag"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Document id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Name."
          },
          "visibility": {
            "type": "string",
            "description": "Recorded audience.",
            "enum": [
              "private",
              "tenant"
            ]
          },
          "plan_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Attached plan UUID.",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "description": "Creation time.",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "description": "Last update.",
            "format": "date-time"
          },
          "etag": {
            "type": "string",
            "description": "Current ETag including quotes."
          },
          "body": {
            "type": "object",
            "additionalProperties": true,
            "description": "Only with include=body."
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "plan-views only: the creator's email; null for a view saved without a signed-in user."
          },
          "version": {
            "type": "integer",
            "description": "assumption-sets only: 1 when created, one more on each PUT. POST /plans assumption_set.version names it.",
            "minimum": 1
          },
          "model_set": {
            "type": "string",
            "description": "assumption-sets only: the body's model_set, the model set the set was made on.",
            "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
          }
        },
        "additionalProperties": false
      },
      "SavedDocList": {
        "type": "object",
        "description": "Saved documents page.",
        "required": [
          "items",
          "next_cursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SavedDocListItem"
            },
            "description": "Newest updated_at first."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Next page, null at end."
          }
        },
        "additionalProperties": false
      },
      "AssumptionSetEcho": {
        "type": "object",
        "description": "The assumption set a plan ran with.",
        "required": [
          "id",
          "version",
          "name",
          "filled"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The set's id.",
            "format": "uuid"
          },
          "version": {
            "type": "integer",
            "description": "The version the plan ran with.",
            "minimum": 1
          },
          "name": {
            "type": "string",
            "description": "The set's name then."
          },
          "filled": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A POST /plans field."
            },
            "description": "The request fields the set filled, in the set's key order. A value they set reads in each well's resolved inputs as the field it filled (plan or plan_formation)."
          }
        },
        "additionalProperties": false
      },
      "AssumptionSetBody": {
        "type": "object",
        "description": "An assumption set's body: plan fields as POST /plans takes them, a pad layout and a price deck. Checked on each save with the parsers that need no dataset; formation names, TIL range and landing are checked when a plan applies the set.",
        "required": [
          "model_set"
        ],
        "properties": {
          "model_set": {
            "type": "string",
            "description": "The model set the set was made on, an id from GET /model-sets; POST /plans applies it only on that set.",
            "pattern": "^[a-z0-9][a-z0-9-]{0,62}$"
          },
          "designs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignInput"
            },
            "description": "Completion designs; every well is forecast with each. Leave out for one design at the recent-completions median. A well's own completions, a scenario's and a pad's or layout's need one design.",
            "minItems": 1,
            "maxItems": 10
          },
          "formations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormationLandingInput"
            },
            "description": "The request's landing per formation, each formation at most once; a landing on the well, its pad, layout, bench or scenario entry beats it. Goes with `wells`, `layout` or `layouts`.\n\nAn entry for a formation no well has is accepted. Completions per formation stay in `designs`. Once an entry sets a landing that a well takes, `inputs.resolved` gives each well's `til_date` and `landing`, and the export's wells table adds `til_date`, `til_layer` and `landing_layer`.",
            "maxItems": 100
          },
          "pad_template": {
            "$ref": "#/components/schemas/PadTemplate"
          },
          "til_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "As POST /plans takes it. Checked as a date at save; its range against the dataset when a plan applies the set.",
            "format": "date"
          },
          "pdp": {
            "type": "boolean",
            "description": "As POST /plans takes it."
          },
          "depletion_chain": {
            "type": "boolean",
            "description": "As POST /plans takes it."
          },
          "eur": {
            "type": "boolean",
            "default": false,
            "description": "Add the EUR (Novi type-curve decline fit) to each oil and gas forecast; GET /dataset eur says whether this server has it (503 if not)."
          },
          "eur_water": {
            "type": "boolean",
            "default": false,
            "description": "Fit water's EUR too, with `decline.water` over the settings at any layer.\n\nAdds `eur` to each water forecast, `water` to the `decline` echo, `totals[].eur` and `inputs.resolved.decline`, and water's columns to the eur, forecast and wells tables, where monthly water runs to the EUR day. BOE never reads it, and oil's and gas's fits are unchanged. Without it, `decline.water` is a 400. Needs `eur: true` (a 400 on eur_water without it)."
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings",
            "description": "Decline fit settings, with eur: true only; any left out take Novi's defaults (GET /dataset eur.defaults), and oil and gas (with eur_water, water) override them per stream. The plan layer: a well, pad, layout, bench, scenario or `formations` entry can set its wells' own, field by field."
          },
          "bands": {
            "type": "boolean",
            "default": false,
            "description": "Add P10/P90 bands to each stream forecast (Novi's predrill bands, same model call); GET /dataset bands says which streams have them, and a request answers 503 when none has."
          },
          "band_eur": {
            "type": "boolean",
            "default": false,
            "description": "Also fit each oil and gas band to an EUR with the decline settings, and water's with eur_water: two more decline fits per such forecast (about three times eur's fitting). Needs bands and eur."
          },
          "economics": {
            "type": "object",
            "description": "A price deck as POST /economics takes it, for clients to send there; POST /plans doesn't read it.",
            "required": [],
            "properties": {
              "deck_id": {
                "type": "string",
                "description": "A deck id, one of every deck the server has; POST /economics checks it against the plan's set.",
                "enum": [
                  "prototype-midland-flat",
                  "house-70-3",
                  "illustrative-haynesville-gas"
                ]
              },
              "deck": {
                "type": "object",
                "description": "Overrides of the deck's values for this request (every deck takes the same ranges); any left out keep the deck's.",
                "required": [],
                "properties": {
                  "oil_price": {
                    "type": "number",
                    "description": "$/bbl; 75 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 300
                  },
                  "oil_differential": {
                    "type": "number",
                    "description": "$/bbl; 4 in the illustrative Midland deck.",
                    "minimum": -50,
                    "maximum": 50
                  },
                  "gas_price": {
                    "type": "number",
                    "description": "$/mcf; 3.5 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 50
                  },
                  "gas_differential": {
                    "type": "number",
                    "description": "$/mcf; 1 in the illustrative Midland deck.",
                    "minimum": -10,
                    "maximum": 10
                  },
                  "ngl_price": {
                    "type": "number",
                    "description": "$/bbl; 26 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 200
                  },
                  "ngl_yield_bbl_per_mmcf": {
                    "type": "number",
                    "description": "bbl/MMcf; 130 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 300
                  },
                  "shrink": {
                    "type": "number",
                    "description": "fraction; 0.8 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 1
                  },
                  "opex_oil": {
                    "type": "number",
                    "description": "$/bbl; 5.5 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "opex_gas": {
                    "type": "number",
                    "description": "$/mcf; 0.5 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 20
                  },
                  "opex_water": {
                    "type": "number",
                    "description": "$/bbl; 0.6 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 20
                  },
                  "royalty": {
                    "type": "number",
                    "description": "fraction; 0.25 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 0.5
                  },
                  "severance_oil": {
                    "type": "number",
                    "description": "fraction; 0.046 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 0.5
                  },
                  "severance_gas": {
                    "type": "number",
                    "description": "fraction; 0.075 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 0.5
                  },
                  "ad_valorem": {
                    "type": "number",
                    "description": "fraction; 0.025 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 0.2
                  },
                  "capex_per_well": {
                    "type": "number",
                    "description": "$; 2500000 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 50000000
                  },
                  "capex_drilling_per_ft": {
                    "type": "number",
                    "description": "$/ft; 150 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 2000
                  },
                  "capex_stimulation_per_ft": {
                    "type": "number",
                    "description": "$/ft; 125 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 2000
                  },
                  "capex_proppant_per_lb": {
                    "type": "number",
                    "description": "$/lb; 0.08 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 2
                  },
                  "capex_fluid_per_bbl": {
                    "type": "number",
                    "description": "$/bbl; 3 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 50
                  },
                  "discount_rate": {
                    "type": "number",
                    "description": "fraction per year; 0.25 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 1
                  }
                },
                "additionalProperties": false
              },
              "conventions": {
                "type": "string",
                "description": "How NPV and payback are counted: prototype, yearly discounting (the app's default), or fe, monthly discounting, which matches Novi's earlier Forecast Engine.",
                "enum": [
                  "prototype",
                  "fe"
                ],
                "default": "prototype"
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "PadTemplate": {
        "type": "object",
        "description": "A pad layout an engineer reuses, checked as POST /layouts/fill checks the same fields. POST /plans doesn't read it: send it as a new pad's layout with that pad's area, as layout or layouts on POST /plans, or to POST /layouts/fill without the benches' landing_fraction and landing_below_top_ft, which it refuses.",
        "required": [
          "benches"
        ],
        "properties": {
          "azimuth_deg": {
            "type": "number",
            "description": "Direction wells are drilled, degrees clockwise from north.",
            "minimum": -360,
            "maximum": 360,
            "default": 0
          },
          "setback_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Feet the wells keep from the unit's outline and holes, from every point of a well in any direction; with setback_end_ft, measured across the well (square to the azimuth).",
            "minimum": 0,
            "maximum": 2640,
            "default": 0
          },
          "setback_end_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Feet each well's heel and toe keep from the outline and holes, in a straight line; the rest of the well may pass closer as long as setback_ft holds across it. With lateral_length_ft, a piece whose heel or toe would fall closer is left out. Every edge gets both rules, whatever its angle.",
            "minimum": 0,
            "maximum": 2640
          },
          "standoff_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Least distance from every lateral to the existing laterals (heel, else surface hole, to bottom hole) in its formation that lie in the unit or within standoff_ft of it, ft. Needs a formation for every bench.",
            "minimum": 0,
            "maximum": 5280
          },
          "min_lateral_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Shortest well, ft: every edge-to-edge chord at least this long is a well, instead of those within 95% of the longest. Not with lateral_length_ft.\n\nA kept chord longer than 30,000 ft between the rounded ends splits into the fewest equal wells of at most 30,000 ft, toe meeting heel; a split piece shorter than min_lateral_ft is left out, so such a chord may give no well.",
            "minimum": 1000,
            "maximum": 30000
          },
          "wells_per_pad": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Groups the wells into pads of this many, numbered from 0 in each well's pad; a pad never spans two parts or tiers, so the last of each may hold fewer.\n\nA fill's pads only label wells: each well keeps its surface hole and the request's TIL date. To set a pad's values, post the fill's `wells` with `pads`. POST /plans keeps pad keys: with `layout`, the 1-based pad number as text; with `layouts`, the 1-based layout number, a hyphen, then the 1-based pad number. Without wells_per_pad, laid-out wells have no pad key. To price a pad, send its wells (a plan's layout echo `pads`) as a plan scenario's `wells` in POST /economics.",
            "minimum": 1,
            "maximum": 50
          },
          "benches": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A bench: spacing_ft or wells_per_section, and landing_fraction or landing_below_top_ft at most.",
              "required": [
                "formation"
              ],
              "properties": {
                "formation": {
                  "type": "string",
                  "description": "The formation the bench's wells land in."
                },
                "spacing_ft": {
                  "type": "number",
                  "description": "Distance between the bench's wells, ft. Not with wells_per_section.",
                  "minimum": 100,
                  "maximum": 10000
                },
                "wells_per_section": {
                  "type": "number",
                  "description": "Instead of spacing_ft: wells per section, so spacing is 5,280 ft / wells_per_section (within spacing_ft's bounds).",
                  "minimum": 0.528,
                  "maximum": 52.8
                },
                "offset_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Shifts the bench's lines across the azimuth, ft (+ to the right looking along it), to stagger benches; 0, null or absent is no shift.\n\nLines pushed outside the area less setback_ft are dropped, not wrapped round, so a half-spacing stagger often holds one well fewer. A part with a non-zero offset isn't evened out, and in POST /plans' layouts no layout of the plan is, so a stagger set across layouts holds.",
                  "minimum": -10000,
                  "maximum": 10000,
                  "default": 0
                },
                "landing_fraction": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.\n\nThe top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.\n\nThe rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.\n\nTop and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.\n\nNeeds formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:\n\n- its formation has no grid there or no place in the column;\n- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);\n- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;\n- top and base averaged over the ends are under a foot apart: the zone pinches out.\n\nA well's inputs echo it when it was sent.",
                  "minimum": 0,
                  "maximum": 1
                },
                "landing_below_top_ft": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's `subsurface_sampling` (GET /model-sets).",
                  "exclusiveMinimum": -40000,
                  "exclusiveMaximum": 40000
                }
              },
              "additionalProperties": false
            },
            "description": "Benches.",
            "minItems": 1,
            "maxItems": 10
          }
        },
        "additionalProperties": false
      },
      "PlanViewBody": {
        "type": "object",
        "description": "A saved Plans view: send its fields to GET /plans as parameters of the same names, lists joined by commas.",
        "required": [
          "origin"
        ],
        "properties": {
          "origin": {
            "type": "string",
            "description": "The view, as GET /plans `origin`: `v2` plans, `fe` Legacy Forecasts or `all`.",
            "enum": [
              "fe",
              "v2",
              "all"
            ]
          },
          "q": {
            "type": "string",
            "description": "As GET /plans `q`.",
            "maxLength": 200
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A status.",
              "enum": [
                "done",
                "running",
                "error"
              ]
            },
            "description": "As GET /plans `status`, as a list.",
            "uniqueItems": true
          },
          "created_by": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "`me` or a person key.",
              "pattern": "^(me|u_[0-9a-f]{16})$"
            },
            "description": "As GET /plans `created_by`: `me` is whoever opens the view, a person key one teammate.",
            "uniqueItems": true
          },
          "streams": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A set of streams, as `oil-gas`."
            },
            "description": "As GET /plans `streams`, as a list.",
            "uniqueItems": true
          },
          "saved": {
            "type": "boolean",
            "description": "As GET /plans `saved`."
          },
          "shared": {
            "type": "boolean",
            "description": "As GET /plans `shared`."
          },
          "ran_from": {
            "type": "string",
            "description": "As GET /plans `ran_from`.",
            "format": "date-time"
          },
          "ran_to": {
            "type": "string",
            "description": "As GET /plans `ran_to`.",
            "format": "date-time"
          },
          "ran_within": {
            "type": "string",
            "description": "A window that moves, as GET /plans `ran_within`; not with `ran_from` or `ran_to`.",
            "pattern": "^P([1-9][0-9]{0,3}D|[1-9][0-9]{0,2}M)$"
          },
          "sort": {
            "type": "string",
            "description": "As GET /plans `sort`.",
            "enum": [
              "ran_at",
              "-ran_at",
              "name",
              "-name",
              "total",
              "-total",
              "status",
              "-status",
              "created_by",
              "-created_by"
            ]
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A column.",
              "enum": [
                "ran_at",
                "total",
                "streams",
                "status",
                "created_by",
                "saved",
                "shared"
              ]
            },
            "description": "The columns shown beside the name, each once: `ran_at`, `total`, `streams`, `status`, `created_by`, `saved`, `shared`. A client shows them in its own order.",
            "uniqueItems": true
          }
        },
        "additionalProperties": false
      },
      "SourceOptions": {
        "type": "object",
        "description": "How to read the file; every member is optional.",
        "required": [],
        "properties": {
          "format": {
            "type": "string",
            "description": "The file's format, when its header could read as another; absent, the header decides.",
            "enum": [
              "valnav_decline",
              "valnav_constants",
              "novi_arps",
              "combocurve_parameters",
              "mosaic_decline",
              "aries"
            ]
          },
          "units": {
            "type": "string",
            "description": "The file's unit system; absent, a Val Nav units row or a Mosaic file's header unit labels decide, else imperial (bbl/d, Mcf/d; metric m³/d, e³m³/d).",
            "enum": [
              "imperial",
              "metric"
            ]
          },
          "products": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "enum": [
                "oil",
                "gas",
                "water",
                "skip"
              ]
            },
            "maxProperties": 100,
            "description": "A file product (any case and spacing) to the stream it reads as, or skip, as {\"CONDENSATE\": \"skip\"}; a ratio product (GOR, OGR, CGR, WOR, WGR) maps only to its own stream or skip."
          },
          "gas_basis": {
            "type": "string",
            "description": "raw or sales gas; absent, sales when the file names sales gas, else raw.",
            "enum": [
              "raw",
              "sales"
            ]
          },
          "reserves_categories": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A reserves category, any case.",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "The categories to keep; absent keeps every one.",
            "maxItems": 100
          },
          "p_levels": {
            "type": "object",
            "description": "Novi arps.csv only: the reserves category each P-level reads as, each its own, as {\"P10\": \"1P\"}.",
            "required": [],
            "properties": {
              "P10": {
                "type": "string",
                "description": "Its reserves category."
              },
              "P50": {
                "type": "string",
                "description": "Its reserves category; absent, P50."
              },
              "P90": {
                "type": "string",
                "description": "Its reserves category."
              }
            },
            "additionalProperties": false
          },
          "columns": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "maxProperties": 100,
            "description": "A role to the file's header for it, when the file names a column otherwise, as {\"uwi\": \"Well ID\"}; a role the format lacks or a header the file lacks is a 400."
          },
          "sheet": {
            "type": [
              "string",
              "integer"
            ],
            "minLength": 1,
            "maxLength": 200,
            "minimum": 0,
            "description": "An .xlsx file's sheet to read: its name, exact or in any case, or its index from 0, as \"Declines\" or 0; absent, the first. A sheet the workbook lacks is a 400 with details.sheets, and sheet with CSV text a 400."
          }
        },
        "additionalProperties": false
      },
      "ForecastSourceReadRequest": {
        "type": "object",
        "description": "A forecast file in a JSON body.",
        "required": [
          "csv"
        ],
        "properties": {
          "csv": {
            "type": "string",
            "description": "The forecast file's text. Where you can, upload the file itself as multipart/form-data instead."
          },
          "constants_csv": {
            "type": "string",
            "description": "A Val Nav constants CSV's text, read with a Val Nav decline file in csv."
          },
          "options": {
            "$ref": "#/components/schemas/SourceOptions"
          },
          "include": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "An addition to the answer.",
              "enum": [
                "warning_codes",
                "sheets"
              ]
            },
            "description": "warning_codes adds warning_details, each warning's code and fields beside its sentence; sheets adds a workbook's sheet and sheets. Each at most once.",
            "maxItems": 2
          }
        },
        "additionalProperties": false
      },
      "ForecastSourceUpload": {
        "type": "object",
        "description": "A multipart/form-data upload: one file part and optional parts; any other part is a 400.",
        "required": [
          "file"
        ],
        "properties": {
          "file": {
            "type": "string",
            "description": "The forecast CSV or .xlsx workbook, as a file part; CSV text may also come as a text part, read as UTF-8 (a file part reads Windows-1252 too).",
            "format": "binary"
          },
          "constants": {
            "type": "string",
            "description": "A Val Nav constants CSV or .xlsx workbook, as a file part (CSV also as a text part), read with the Val Nav decline file.",
            "format": "binary"
          },
          "options": {
            "type": "string",
            "description": "As options in the JSON body, as JSON text: {\"units\": \"metric\"}."
          },
          "include": {
            "type": "string",
            "description": "As include in the JSON body, as JSON text: [\"warning_codes\", \"sheets\"]."
          }
        },
        "additionalProperties": false
      },
      "ForecastSourceSaveRequest": {
        "type": "object",
        "description": "A forecast file to save, in a JSON body.",
        "required": [
          "csv",
          "name"
        ],
        "properties": {
          "csv": {
            "type": "string",
            "description": "As in POST /forecast-sources/read."
          },
          "constants_csv": {
            "type": "string",
            "description": "As in POST /forecast-sources/read."
          },
          "options": {
            "$ref": "#/components/schemas/SourceOptions"
          },
          "include": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "An addition to the answer.",
              "enum": [
                "warning_codes",
                "sheets"
              ]
            },
            "description": "warning_codes adds warning_details, each warning's code and fields beside its sentence; sheets adds a workbook's sheet and sheets. Each at most once.",
            "maxItems": 2
          },
          "name": {
            "type": "string",
            "description": "The source's name.",
            "minLength": 1,
            "maxLength": 100
          },
          "visibility": {
            "type": "string",
            "description": "private (the default) answers only its signed-in creator; tenant every user of the tenant.",
            "enum": [
              "private",
              "tenant"
            ]
          },
          "plan_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "A done plan to link, which linking saves; null or absent links none.",
            "format": "uuid"
          },
          "file_name": {
            "type": "string",
            "description": "The file's name, kept with the source; absent, null.",
            "minLength": 1,
            "maxLength": 200
          }
        },
        "additionalProperties": false
      },
      "ForecastSourceSaveUpload": {
        "type": "object",
        "description": "A multipart/form-data upload to save.",
        "required": [
          "file",
          "name"
        ],
        "properties": {
          "file": {
            "type": "string",
            "description": "As in POST /forecast-sources/read; a file part's name is kept with the source.",
            "format": "binary"
          },
          "constants": {
            "type": "string",
            "description": "As in POST /forecast-sources/read.",
            "format": "binary"
          },
          "options": {
            "type": "string",
            "description": "As in POST /forecast-sources/read."
          },
          "include": {
            "type": "string",
            "description": "As include in the JSON body, as JSON text: [\"warning_codes\", \"sheets\"]."
          },
          "name": {
            "type": "string",
            "description": "The source's name, 1 to 100 characters."
          },
          "visibility": {
            "type": "string",
            "description": "private or tenant, as in the JSON body."
          },
          "plan_id": {
            "type": "string",
            "description": "A done plan's id to link."
          }
        },
        "additionalProperties": false
      },
      "SourceSegment": {
        "type": "object",
        "description": "A decline segment, as Novi's Arps decline calculation runs it.",
        "required": [
          "start",
          "qi",
          "di",
          "b"
        ],
        "properties": {
          "start": {
            "type": "number",
            "description": "The day it starts, from day 0."
          },
          "end": {
            "type": [
              "number",
              "null"
            ],
            "description": "The day it ends; absent or null runs to qf, df or the curve's end."
          },
          "qi": {
            "type": "number",
            "description": "Rate at start: bbl/d for oil and water, mcf/d for gas; for a ratio, the ratio (GOR scf/bbl, OGR, CGR and WGR bbl/MMcf, WOR bbl/bbl)."
          },
          "di": {
            "type": "number",
            "description": "Nominal decline per year at start; below 0 for an incline."
          },
          "b": {
            "type": "number",
            "description": "Arps b: 0 exponential, 1 harmonic, -1 a straight line."
          },
          "qf": {
            "type": [
              "number",
              "null"
            ],
            "description": "The rate it ends at."
          },
          "df": {
            "type": [
              "number",
              "null"
            ],
            "description": "The nominal decline it ends at."
          },
          "max_rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "A cap on the rate."
          },
          "slope": {
            "type": "string",
            "description": "What a ratio declines with: time or the parent stream's cumulative volume.",
            "enum": [
              "time",
              "volume"
            ]
          }
        },
        "additionalProperties": false
      },
      "SourceCurve": {
        "type": "object",
        "description": "A curve: one well, reserves category, design and stream.",
        "required": [
          "well_id",
          "reserves_category",
          "design",
          "stream",
          "product",
          "ratio",
          "profile",
          "start_date",
          "template",
          "segments"
        ],
        "properties": {
          "well_id": {
            "type": "string",
            "description": "The Well ID, as the file has it."
          },
          "reserves_category": {
            "type": "string",
            "description": "Its reserves category (a Novi P-level reads as P50 or its options.p_levels category)."
          },
          "design": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its completion design (Novi arps.csv), or null."
          },
          "stream": {
            "type": "string",
            "description": "The stream it forecasts.",
            "enum": [
              "oil",
              "gas",
              "water"
            ]
          },
          "product": {
            "type": "string",
            "description": "The file's product it came from."
          },
          "ratio": {
            "type": [
              "string",
              "null"
            ],
            "description": "The ratio it is, its stream from its parent's, or null.",
            "enum": [
              "gor",
              "ogr",
              "cgr",
              "wor",
              "wgr",
              null
            ]
          },
          "profile": {
            "type": "string",
            "description": "The decline conventions it runs under (GET /conventions include=decline_profiles).",
            "enum": [
              "valnav",
              "mosaic",
              "combocurve",
              "novi",
              "aries"
            ]
          },
          "start_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "The date of day 0, or null when the file counts ip days."
          },
          "template": {
            "type": [
              "string",
              "null"
            ],
            "description": "The Val Nav template it matched, ComboCurve's Segment Types in order, or null."
          },
          "segments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceSegment"
            },
            "description": "Its segments in order, each starting where the one before ends."
          }
        },
        "additionalProperties": false
      },
      "SourceCurveVolumes": {
        "type": "object",
        "description": "A stored curve with its volumes (include=volumes).",
        "required": [
          "well_id",
          "reserves_category",
          "design",
          "stream",
          "product",
          "ratio",
          "profile",
          "start_date",
          "template",
          "segments",
          "volumes"
        ],
        "properties": {
          "well_id": {
            "type": "string",
            "description": "The Well ID, as the file has it."
          },
          "reserves_category": {
            "type": "string",
            "description": "Its reserves category (a Novi P-level reads as P50 or its options.p_levels category)."
          },
          "design": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its completion design (Novi arps.csv), or null."
          },
          "stream": {
            "type": "string",
            "description": "The stream it forecasts.",
            "enum": [
              "oil",
              "gas",
              "water"
            ]
          },
          "product": {
            "type": "string",
            "description": "The file's product it came from."
          },
          "ratio": {
            "type": [
              "string",
              "null"
            ],
            "description": "The ratio it is, its stream from its parent's, or null.",
            "enum": [
              "gor",
              "ogr",
              "cgr",
              "wor",
              "wgr",
              null
            ]
          },
          "profile": {
            "type": "string",
            "description": "The decline conventions it runs under (GET /conventions include=decline_profiles).",
            "enum": [
              "valnav",
              "mosaic",
              "combocurve",
              "novi",
              "aries"
            ]
          },
          "start_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "The date of day 0, or null when the file counts ip days."
          },
          "template": {
            "type": [
              "string",
              "null"
            ],
            "description": "The Val Nav template it matched, ComboCurve's Segment Types in order, or null."
          },
          "segments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceSegment"
            },
            "description": "Its segments in order, each starting where the one before ends."
          },
          "volumes": {
            "type": "object",
            "description": "Volumes from Novi's Arps decline calculation.",
            "required": [
              "unit",
              "ip_days",
              "values",
              "eur"
            ],
            "properties": {
              "unit": {
                "type": "string",
                "description": "bbl for oil and water, mcf for gas.",
                "enum": [
                  "bbl",
                  "mcf"
                ]
              },
              "ip_days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "description": "An ip_day."
                },
                "description": "The days asked, ascending."
              },
              "values": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "number"
                },
                "description": "Cumulative volume at each ip_day, rounded to 0.1; null when the engine can't run the curve."
              },
              "eur": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Volume to the curve's end, rounded to 0.1."
              },
              "error": {
                "type": "string",
                "description": "Why the engine can't run it."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SourceRow": {
        "type": "object",
        "description": "A row with an issue.",
        "required": [
          "file",
          "id",
          "well_id",
          "product",
          "segment",
          "left_out",
          "issues"
        ],
        "properties": {
          "file": {
            "type": "string",
            "description": "The part or field the row is in: file, constants, csv or constants_csv."
          },
          "id": {
            "type": "integer",
            "description": "Its data row in that file, from 0.",
            "minimum": 0
          },
          "well_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its Well ID, or null."
          },
          "product": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its product, or null."
          },
          "segment": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Its segment number, or null."
          },
          "left_out": {
            "type": "boolean",
            "description": "True when its curve was left out."
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sentence."
            },
            "description": "What was wrong with it."
          }
        },
        "additionalProperties": false
      },
      "SourceRead": {
        "type": "object",
        "description": "A forecast file read into curves.",
        "required": [
          "format",
          "detected_from",
          "units",
          "products",
          "gas_basis",
          "reserves_categories",
          "curves",
          "rows",
          "warnings"
        ],
        "properties": {
          "format": {
            "type": "string",
            "description": "The format read.",
            "enum": [
              "valnav_decline",
              "valnav_constants",
              "novi_arps",
              "combocurve_parameters",
              "mosaic_decline",
              "aries"
            ]
          },
          "sheet": {
            "type": "string",
            "description": "The sheet read; only with include [\"sheets\"], for a workbook file."
          },
          "sheets": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sheet's name; one over 31 characters is cut to 31 and ends in …."
            },
            "description": "Every sheet in workbook order, chartsheets included, so a position is the index options.sheet takes; only with include [\"sheets\"], for a workbook file, never the constants part's."
          },
          "detected_from": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A header, units row, or PRODUCTION."
            },
            "description": "The headers that picked the format; ARIES text gives [\"PRODUCTION\"], also when options.format named it."
          },
          "units": {
            "type": "object",
            "description": "Units.",
            "required": [
              "system",
              "from",
              "rates",
              "ratios",
              "row"
            ],
            "properties": {
              "system": {
                "type": "string",
                "description": "The unit system read.",
                "enum": [
                  "imperial",
                  "metric"
                ]
              },
              "from": {
                "type": "string",
                "description": "What set it.",
                "enum": [
                  "options",
                  "units row",
                  "format",
                  "default"
                ]
              },
              "rates": {
                "type": "object",
                "description": "The rate units read, converted to bbl/d and mcf/d.",
                "required": [
                  "oil",
                  "gas",
                  "water"
                ],
                "properties": {
                  "oil": {
                    "type": "string",
                    "description": "Its rate unit."
                  },
                  "gas": {
                    "type": "string",
                    "description": "Its rate unit."
                  },
                  "water": {
                    "type": "string",
                    "description": "Its rate unit."
                  }
                },
                "additionalProperties": false
              },
              "ratios": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "A ratio product to its unit."
              },
              "row": {
                "type": [
                  "object",
                  "null"
                ],
                "additionalProperties": {
                  "type": "string"
                },
                "description": "A Val Nav units row or a Mosaic file's header unit labels, header to unit, or null."
              }
            },
            "additionalProperties": false
          },
          "products": {
            "type": "object",
            "description": "Products.",
            "required": [
              "found",
              "mapped",
              "skipped"
            ],
            "properties": {
              "found": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A product.",
                  "required": [
                    "value",
                    "curves"
                  ],
                  "properties": {
                    "value": {
                      "type": "string",
                      "description": "As the file has it."
                    },
                    "curves": {
                      "type": "integer",
                      "description": "Curves.",
                      "minimum": 0
                    }
                  },
                  "additionalProperties": false
                },
                "description": "Every product in the file."
              },
              "mapped": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A product read.",
                  "required": [
                    "value",
                    "stream",
                    "from"
                  ],
                  "properties": {
                    "value": {
                      "type": "string",
                      "description": "The product."
                    },
                    "stream": {
                      "type": "string",
                      "description": "The stream it reads as.",
                      "enum": [
                        "oil",
                        "gas",
                        "water"
                      ]
                    },
                    "from": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The parent stream of a ratio.",
                      "enum": [
                        "oil",
                        "gas",
                        null
                      ]
                    }
                  },
                  "additionalProperties": false
                },
                "description": "Products read."
              },
              "skipped": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A product.",
                  "required": [
                    "value",
                    "curves"
                  ],
                  "properties": {
                    "value": {
                      "type": "string",
                      "description": "As the file has it."
                    },
                    "curves": {
                      "type": "integer",
                      "description": "Curves.",
                      "minimum": 0
                    }
                  },
                  "additionalProperties": false
                },
                "description": "Products left out."
              }
            },
            "additionalProperties": false
          },
          "gas_basis": {
            "type": "string",
            "description": "raw or sales gas.",
            "enum": [
              "raw",
              "sales"
            ]
          },
          "reserves_categories": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A category.",
              "required": [
                "value",
                "curves",
                "kept"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "description": "As the file has it."
                },
                "curves": {
                  "type": "integer",
                  "description": "Curves.",
                  "minimum": 0
                },
                "kept": {
                  "type": "boolean",
                  "description": "Whether options.reserves_categories keeps it."
                }
              },
              "additionalProperties": false
            },
            "description": "Every reserves category with a curve."
          },
          "curves": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceCurve"
            },
            "description": "The curves read, in file order."
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceRow"
            },
            "description": "Only the rows with an issue."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sentence."
            },
            "description": "What to check."
          },
          "warning_details": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceReadWarning"
            },
            "description": "Only with include warning_codes: each warning's code and fields, one per warning, in the same order."
          }
        },
        "additionalProperties": false
      },
      "ForecastSourceSaved": {
        "type": "object",
        "description": "The read, and the source saved from it.",
        "required": [
          "format",
          "detected_from",
          "units",
          "products",
          "gas_basis",
          "reserves_categories",
          "curves",
          "rows",
          "warnings",
          "source"
        ],
        "properties": {
          "format": {
            "type": "string",
            "description": "The format read.",
            "enum": [
              "valnav_decline",
              "valnav_constants",
              "novi_arps",
              "combocurve_parameters",
              "mosaic_decline",
              "aries"
            ]
          },
          "sheet": {
            "type": "string",
            "description": "The sheet read; only with include [\"sheets\"], for a workbook file."
          },
          "sheets": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sheet's name; one over 31 characters is cut to 31 and ends in …."
            },
            "description": "Every sheet in workbook order, chartsheets included, so a position is the index options.sheet takes; only with include [\"sheets\"], for a workbook file, never the constants part's."
          },
          "detected_from": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A header, units row, or PRODUCTION."
            },
            "description": "The headers that picked the format; ARIES text gives [\"PRODUCTION\"], also when options.format named it."
          },
          "units": {
            "type": "object",
            "description": "Units.",
            "required": [
              "system",
              "from",
              "rates",
              "ratios",
              "row"
            ],
            "properties": {
              "system": {
                "type": "string",
                "description": "The unit system read.",
                "enum": [
                  "imperial",
                  "metric"
                ]
              },
              "from": {
                "type": "string",
                "description": "What set it.",
                "enum": [
                  "options",
                  "units row",
                  "format",
                  "default"
                ]
              },
              "rates": {
                "type": "object",
                "description": "The rate units read, converted to bbl/d and mcf/d.",
                "required": [
                  "oil",
                  "gas",
                  "water"
                ],
                "properties": {
                  "oil": {
                    "type": "string",
                    "description": "Its rate unit."
                  },
                  "gas": {
                    "type": "string",
                    "description": "Its rate unit."
                  },
                  "water": {
                    "type": "string",
                    "description": "Its rate unit."
                  }
                },
                "additionalProperties": false
              },
              "ratios": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "A ratio product to its unit."
              },
              "row": {
                "type": [
                  "object",
                  "null"
                ],
                "additionalProperties": {
                  "type": "string"
                },
                "description": "A Val Nav units row or a Mosaic file's header unit labels, header to unit, or null."
              }
            },
            "additionalProperties": false
          },
          "products": {
            "type": "object",
            "description": "Products.",
            "required": [
              "found",
              "mapped",
              "skipped"
            ],
            "properties": {
              "found": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A product.",
                  "required": [
                    "value",
                    "curves"
                  ],
                  "properties": {
                    "value": {
                      "type": "string",
                      "description": "As the file has it."
                    },
                    "curves": {
                      "type": "integer",
                      "description": "Curves.",
                      "minimum": 0
                    }
                  },
                  "additionalProperties": false
                },
                "description": "Every product in the file."
              },
              "mapped": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A product read.",
                  "required": [
                    "value",
                    "stream",
                    "from"
                  ],
                  "properties": {
                    "value": {
                      "type": "string",
                      "description": "The product."
                    },
                    "stream": {
                      "type": "string",
                      "description": "The stream it reads as.",
                      "enum": [
                        "oil",
                        "gas",
                        "water"
                      ]
                    },
                    "from": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The parent stream of a ratio.",
                      "enum": [
                        "oil",
                        "gas",
                        null
                      ]
                    }
                  },
                  "additionalProperties": false
                },
                "description": "Products read."
              },
              "skipped": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A product.",
                  "required": [
                    "value",
                    "curves"
                  ],
                  "properties": {
                    "value": {
                      "type": "string",
                      "description": "As the file has it."
                    },
                    "curves": {
                      "type": "integer",
                      "description": "Curves.",
                      "minimum": 0
                    }
                  },
                  "additionalProperties": false
                },
                "description": "Products left out."
              }
            },
            "additionalProperties": false
          },
          "gas_basis": {
            "type": "string",
            "description": "raw or sales gas.",
            "enum": [
              "raw",
              "sales"
            ]
          },
          "reserves_categories": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A category.",
              "required": [
                "value",
                "curves",
                "kept"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "description": "As the file has it."
                },
                "curves": {
                  "type": "integer",
                  "description": "Curves.",
                  "minimum": 0
                },
                "kept": {
                  "type": "boolean",
                  "description": "Whether options.reserves_categories keeps it."
                }
              },
              "additionalProperties": false
            },
            "description": "Every reserves category with a curve."
          },
          "curves": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceCurve"
            },
            "description": "The curves read, in file order."
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceRow"
            },
            "description": "Only the rows with an issue."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sentence."
            },
            "description": "What to check."
          },
          "warning_details": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceReadWarning"
            },
            "description": "Only with include warning_codes: each warning's code and fields, one per warning, in the same order."
          },
          "source": {
            "$ref": "#/components/schemas/ForecastSource"
          }
        },
        "additionalProperties": false
      },
      "SourceReadWarning": {
        "type": "object",
        "description": "A read warning with its code and fields; each code carries only the fields its code lists.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable code; more may come. Each code carries only the fields listed with it.\n\n- `workbook_first_sheet`: file, sheet, sheet_count\n- `formulas_without_values`: file, sheet, cell_count\n- `constants_without_units`: file\n- `constants_on_time`: file, row_count\n- `constants_cut_off`: file, row_count\n- `series_left_out`: file, row_count, series\n- `product_not_found`: product\n- `reserves_category_not_found`: reserves_category\n- `unit_not_recognized`: label, from, quantity, unit\n- `curves_left_out`: curve_count, total_curve_count\n- `rows_without_curve`: row_count\n- `p_levels_not_read`: format\n- `p_levels_left_out`: curve_count\n- `condensate_as_oil`: product\n- `sales_gas`: product\n- `mixed_gas_basis`: sales_product, raw_product\n- `default_units`: system, rates\n- `constants_only`\n- `multiple_reserves_categories`: well_count\n- `multiple_designs`: well_count\n- `sections_not_read`: file, row_count"
          },
          "message": {
            "type": "string",
            "description": "Its sentence in warnings, written for API callers."
          },
          "file": {
            "type": "string",
            "description": "The part or field it is about: file, constants, csv or constants_csv."
          },
          "sheet": {
            "type": "string",
            "description": "The workbook sheet read, as the sentence names it."
          },
          "sheet_count": {
            "type": "integer",
            "description": "Sheets in the workbook.",
            "minimum": 0
          },
          "cell_count": {
            "type": "integer",
            "description": "Formula cells without a saved value.",
            "minimum": 0
          },
          "row_count": {
            "type": "integer",
            "description": "Rows it counts.",
            "minimum": 0
          },
          "series": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A ComboCurve series."
            },
            "description": "The series left out."
          },
          "product": {
            "type": "string",
            "description": "The product, as the file or options.products spells it."
          },
          "reserves_category": {
            "type": "string",
            "description": "The category, as options.reserves_categories sent it."
          },
          "label": {
            "type": "string",
            "description": "The unit label the file gives."
          },
          "from": {
            "type": "string",
            "description": "Where the label is.",
            "enum": [
              "header",
              "units row"
            ]
          },
          "quantity": {
            "type": "string",
            "description": "What the label was read for: oil and water rates, gas rates or a ratio.",
            "enum": [
              "oil_water_rates",
              "gas_rates",
              "gor",
              "ogr",
              "cgr",
              "wor",
              "wgr"
            ]
          },
          "unit": {
            "type": "string",
            "description": "The unit it reads in instead."
          },
          "curve_count": {
            "type": "integer",
            "description": "Curves it counts.",
            "minimum": 0
          },
          "total_curve_count": {
            "type": "integer",
            "description": "Curves the file made.",
            "minimum": 0
          },
          "format": {
            "type": "string",
            "description": "The format read.",
            "enum": [
              "valnav_decline",
              "valnav_constants",
              "novi_arps",
              "combocurve_parameters",
              "mosaic_decline",
              "aries"
            ]
          },
          "sales_product": {
            "type": "string",
            "description": "The sales gas product."
          },
          "raw_product": {
            "type": "string",
            "description": "The raw gas product."
          },
          "system": {
            "type": "string",
            "description": "The unit system read.",
            "enum": [
              "imperial",
              "metric"
            ]
          },
          "rates": {
            "type": "object",
            "description": "The rate units read, as units.rates.",
            "required": [
              "oil",
              "gas",
              "water"
            ],
            "properties": {
              "oil": {
                "type": "string",
                "description": "Its rate unit."
              },
              "gas": {
                "type": "string",
                "description": "Its rate unit."
              },
              "water": {
                "type": "string",
                "description": "Its rate unit."
              }
            },
            "additionalProperties": false
          },
          "well_count": {
            "type": "integer",
            "description": "Wells it counts.",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "ForecastSource": {
        "type": "object",
        "description": "A forecast source.",
        "required": [
          "id",
          "name",
          "format",
          "units",
          "conventions",
          "gas_basis",
          "curve_count",
          "well_count",
          "file",
          "visibility",
          "created_by",
          "created_at",
          "updated_at",
          "plan_id",
          "plan_linked",
          "etag",
          "reserves_categories",
          "pairs",
          "read_report"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Source id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Name."
          },
          "format": {
            "type": "string",
            "description": "The file's format.",
            "enum": [
              "valnav_decline",
              "valnav_constants",
              "novi_arps",
              "combocurve_parameters",
              "mosaic_decline",
              "aries"
            ]
          },
          "units": {
            "type": "string",
            "description": "The file's unit system; curves are stored in bbl/d and mcf/d.",
            "enum": [
              "imperial",
              "metric"
            ]
          },
          "conventions": {
            "type": "string",
            "description": "The decline conventions its curves run under.",
            "enum": [
              "valnav",
              "mosaic",
              "combocurve",
              "novi",
              "aries"
            ]
          },
          "gas_basis": {
            "type": "string",
            "description": "raw or sales gas.",
            "enum": [
              "raw",
              "sales"
            ]
          },
          "curve_count": {
            "type": "integer",
            "description": "Curves.",
            "minimum": 0
          },
          "well_count": {
            "type": "integer",
            "description": "Distinct Well IDs.",
            "minimum": 0
          },
          "file": {
            "type": "object",
            "description": "The file read; the file itself isn't kept.",
            "required": [
              "name",
              "bytes",
              "sha256"
            ],
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The uploaded file's name, or JSON file_name; null without one."
              },
              "bytes": {
                "type": "integer",
                "description": "Its size.",
                "minimum": 0
              },
              "sha256": {
                "type": "string",
                "description": "Its SHA-256, hex."
              }
            },
            "additionalProperties": false
          },
          "visibility": {
            "type": "string",
            "description": "private answers only its creator; tenant every user of the tenant.",
            "enum": [
              "private",
              "tenant"
            ]
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "The signed-in creator's email; null for a server's configured user."
          },
          "created_at": {
            "type": "string",
            "description": "Creation time.",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "description": "Last change.",
            "format": "date-time"
          },
          "plan_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The linked plan, or null when none is linked. A plan that is gone or that the caller can't read stays here with `plan_linked: false`.",
            "format": "uuid"
          },
          "plan_linked": {
            "type": "boolean",
            "description": "Whether plan_id names a plan the caller can read: false with a plan_id when that plan is gone or hidden from the caller."
          },
          "etag": {
            "type": "string",
            "description": "Current ETag including quotes; send as If-Match."
          },
          "reserves_categories": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A category.",
              "required": [
                "value",
                "curves"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "description": "As the file has it."
                },
                "curves": {
                  "type": "integer",
                  "description": "Curves.",
                  "minimum": 0
                }
              },
              "additionalProperties": false
            },
            "description": "Its reserves categories."
          },
          "pairs": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Source Well IDs to the linked plan's well indexes; null without pairs. A gone link (`plan_linked: false`) keeps them, a start for pairing with another plan: PATCH with plan_id and pairs."
          },
          "read_report": {
            "type": "object",
            "description": "What the read left out.",
            "required": [
              "rows"
            ],
            "properties": {
              "rows": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A row.",
                  "required": [
                    "file",
                    "id",
                    "issues"
                  ],
                  "properties": {
                    "file": {
                      "type": "string",
                      "description": "The part or field the row is in: file, constants, csv or constants_csv."
                    },
                    "id": {
                      "type": "integer",
                      "description": "Its data row in that file, from 0.",
                      "minimum": 0
                    },
                    "issues": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A sentence."
                      },
                      "description": "What was wrong."
                    }
                  },
                  "additionalProperties": false
                },
                "description": "The rows with an issue."
              }
            },
            "additionalProperties": false
          },
          "curves": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceCurveVolumes"
            },
            "description": "Only with include=volumes: the stored curves, in file order."
          }
        },
        "additionalProperties": false
      },
      "ForecastSourceListItem": {
        "type": "object",
        "description": "A listed forecast source.",
        "required": [
          "id",
          "name",
          "format",
          "units",
          "conventions",
          "gas_basis",
          "curve_count",
          "well_count",
          "file",
          "visibility",
          "created_by",
          "created_at",
          "updated_at",
          "plan_id",
          "plan_linked",
          "etag"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Source id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Name."
          },
          "format": {
            "type": "string",
            "description": "The file's format.",
            "enum": [
              "valnav_decline",
              "valnav_constants",
              "novi_arps",
              "combocurve_parameters",
              "mosaic_decline",
              "aries"
            ]
          },
          "units": {
            "type": "string",
            "description": "The file's unit system; curves are stored in bbl/d and mcf/d.",
            "enum": [
              "imperial",
              "metric"
            ]
          },
          "conventions": {
            "type": "string",
            "description": "The decline conventions its curves run under.",
            "enum": [
              "valnav",
              "mosaic",
              "combocurve",
              "novi",
              "aries"
            ]
          },
          "gas_basis": {
            "type": "string",
            "description": "raw or sales gas.",
            "enum": [
              "raw",
              "sales"
            ]
          },
          "curve_count": {
            "type": "integer",
            "description": "Curves.",
            "minimum": 0
          },
          "well_count": {
            "type": "integer",
            "description": "Distinct Well IDs.",
            "minimum": 0
          },
          "file": {
            "type": "object",
            "description": "The file read; the file itself isn't kept.",
            "required": [
              "name",
              "bytes",
              "sha256"
            ],
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The uploaded file's name, or JSON file_name; null without one."
              },
              "bytes": {
                "type": "integer",
                "description": "Its size.",
                "minimum": 0
              },
              "sha256": {
                "type": "string",
                "description": "Its SHA-256, hex."
              }
            },
            "additionalProperties": false
          },
          "visibility": {
            "type": "string",
            "description": "private answers only its creator; tenant every user of the tenant.",
            "enum": [
              "private",
              "tenant"
            ]
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "The signed-in creator's email; null for a server's configured user."
          },
          "created_at": {
            "type": "string",
            "description": "Creation time.",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "description": "Last change.",
            "format": "date-time"
          },
          "plan_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The linked plan, or null when none is linked. A plan that is gone or that the caller can't read stays here with `plan_linked: false`.",
            "format": "uuid"
          },
          "plan_linked": {
            "type": "boolean",
            "description": "Whether plan_id names a plan the caller can read: false with a plan_id when that plan is gone or hidden from the caller."
          },
          "etag": {
            "type": "string",
            "description": "Current ETag including quotes; send as If-Match."
          }
        },
        "additionalProperties": false
      },
      "ForecastSourceList": {
        "type": "object",
        "description": "Forecast sources page.",
        "required": [
          "items",
          "next_cursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ForecastSourceListItem"
            },
            "description": "Newest first."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Next page, null at end."
          }
        },
        "additionalProperties": false
      },
      "ForecastSourcePatch": {
        "type": "object",
        "description": "Fields to change, at least one.",
        "required": [],
        "properties": {
          "name": {
            "type": "string",
            "description": "The new name.",
            "minLength": 1,
            "maxLength": 100
          },
          "visibility": {
            "type": "string",
            "description": "private (its signed-in creator only) or tenant.",
            "enum": [
              "private",
              "tenant"
            ]
          },
          "plan_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "A done plan to link, which linking saves; null unlinks.",
            "format": "uuid"
          },
          "pairs": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Source Well IDs to the linked plan's well indexes, as {\"W-1\": 0}; null clears them."
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "Plan": {
        "type": "object",
        "description": "A plan.",
        "required": [
          "id",
          "name",
          "status",
          "pdp",
          "total",
          "done",
          "progress",
          "created_at",
          "seconds",
          "designs",
          "error",
          "totals",
          "links"
        ],
        "properties": {
          "storage": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PlanStorage"
              },
              {
                "type": "null"
              }
            ],
            "description": "Only with include=storage or on updatePlan. Null without a state store."
          },
          "request": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PlanRequest"
              },
              {
                "type": "null"
              }
            ],
            "description": "Only with include=request: the body POST /plans accepted, keys as sent after an assumption set's fill, without callback_url and dry_run. A field sent as null comes back null unless the set filled it; a plan made with from_plan carries its source plan's body. Null for an older plan, one made through the legacy POST /api/plan, or one re-run from either."
          },
          "id": {
            "type": "string",
            "description": "Plan id.",
            "format": "uuid"
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Plan name."
          },
          "from_plan": {
            "type": "string",
            "description": "Only on a plan made with from_plan: the plan whose stored request this one ran again.",
            "format": "uuid"
          },
          "assumption_set": {
            "$ref": "#/components/schemas/AssumptionSetEcho",
            "description": "Only on a plan made with assumption_set, or with from_plan from one: the set it ran with."
          },
          "status": {
            "type": "string",
            "description": "running, then done or error.",
            "enum": [
              "running",
              "done",
              "error"
            ]
          },
          "pdp": {
            "type": "boolean",
            "description": "Whether existing wells are in spacing."
          },
          "total": {
            "type": "integer",
            "description": "Wells."
          },
          "done": {
            "type": "integer",
            "description": "Wells finished; with per_well_errors, a well that could not be placed counts as finished."
          },
          "failed_wells": {
            "type": "object",
            "description": "Present with per_well_errors, including while running and on error; a failed well's plan neighbors are spaced and forecast without it.",
            "required": [
              "count",
              "wells"
            ],
            "properties": {
              "count": {
                "type": "integer",
                "description": "Every well that could not be placed."
              },
              "wells": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A failed well.",
                  "required": [
                    "index",
                    "field",
                    "message"
                  ],
                  "properties": {
                    "index": {
                      "type": "integer",
                      "description": "Plan well index."
                    },
                    "field": {
                      "type": "string",
                      "description": "Placement field.",
                      "enum": [
                        "tvd_ft",
                        "landing_below_top_ft",
                        "landing_fraction",
                        "formation"
                      ]
                    },
                    "message": {
                      "type": "string",
                      "description": "Why the well could not be placed."
                    }
                  },
                  "additionalProperties": false
                },
                "description": "First failed wells, lowest index first.",
                "maxItems": 100
              }
            },
            "additionalProperties": false
          },
          "progress": {
            "type": "number",
            "description": "Share of the work done: wells weighted by the worker steps (spacing, spacing features, forecast) their chunks have finished; with per_well_errors, a well that could not be placed counts as finished.",
            "minimum": 0,
            "maximum": 1
          },
          "steps": {
            "type": "object",
            "description": "While running: chunks (up to 1,000 wells) in each worker step now.",
            "required": [
              "spacing",
              "calc",
              "forecast"
            ],
            "properties": {
              "spacing": {
                "type": "integer",
                "description": "Chunks in spacing."
              },
              "calc": {
                "type": "integer",
                "description": "Chunks in the spacing feature step."
              },
              "forecast": {
                "type": "integer",
                "description": "Chunks in forecast."
              },
              "eur": {
                "type": "integer",
                "description": "With eur: true, chunks fitting EUR."
              },
              "chain": {
                "type": "integer",
                "description": "With depletion_chain applied: wave passes running (one design's production pass and re-forecast for up to 1,000 wells)."
              }
            },
            "additionalProperties": false
          },
          "created_at": {
            "type": "string",
            "description": "Start time.",
            "format": "date-time"
          },
          "seconds": {
            "type": "number",
            "description": "Run time so far, or in total once finished."
          },
          "designs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Design"
            },
            "description": "The completion designs every well runs with."
          },
          "scenarios": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScenarioEcho"
            },
            "description": "When the request sent scenarios: each, in the order its first well came, with its well count."
          },
          "layout": {
            "$ref": "#/components/schemas/LayoutEcho",
            "description": "When the request sent layout: what was laid out."
          },
          "layouts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanLayoutEcho"
            },
            "description": "When the request sent layouts: what each laid out, in order."
          },
          "decline": {
            "$ref": "#/components/schemas/Decline",
            "description": "With eur: true, the plan's decline settings, which a well may override (`per_well`)."
          },
          "bands": {
            "$ref": "#/components/schemas/BandsEcho",
            "description": "With bands: true, the bands every forecast carries."
          },
          "depletion_chain": {
            "$ref": "#/components/schemas/DepletionChainEcho",
            "description": "With the chain on: depletion_chain true, or absent on a set whose models read neighbors' production. What the chain read and did."
          },
          "error": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ErrorBody"
              },
              {
                "type": "null"
              }
            ],
            "description": "Why the plan failed."
          },
          "totals": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PlanTotals"
                },
                "description": "One per design; with scenarios, one per scenario and design."
              },
              {
                "type": "null"
              }
            ],
            "description": "Totals per design, once done. On a plan made with scenarios, one per scenario and design, scenario by scenario in the order of `scenarios`, each with its `scenario`: there totals[d] is not design d."
          },
          "callbacks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportCallback"
            },
            "description": "Only on a plan made with callback_url: its delivery, as an export's callbacks show theirs.",
            "maxItems": 1
          },
          "links": {
            "type": "object",
            "description": "Related URLs.",
            "required": [
              "self",
              "wells"
            ],
            "properties": {
              "self": {
                "type": "string",
                "description": "This plan."
              },
              "wells": {
                "type": "string",
                "description": "This plan with its wells."
              },
              "export": {
                "type": "string",
                "description": "The zip export; absent on a Legacy Forecast (origin.engine fe): export it with POST /exports."
              }
            },
            "additionalProperties": false
          },
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanWellSummary"
            },
            "description": "With include=wells: the wells, or while running those finished so far."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "With include=wells: cursor for the next page of wells, or while running for the wells that finish next."
          },
          "matched": {
            "type": "integer",
            "description": "With include=wells and a `scenario`, `formation`, `q` or `pad` that filters: the wells passing them and any `wells`, finished or not, over every page. A failed plan returns no wells, and no `matched`.",
            "minimum": 0
          },
          "origin": {
            "oneOf": [
              {
                "type": "object",
                "description": "A v2 plan.",
                "required": [
                  "engine"
                ],
                "properties": {
                  "engine": {
                    "const": "v2",
                    "description": "A plan this API ran."
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "object",
                "description": "A Legacy Forecast.",
                "required": [
                  "engine",
                  "job_id",
                  "run",
                  "ran_at"
                ],
                "properties": {
                  "engine": {
                    "const": "fe",
                    "description": "A Legacy Forecast, read only. Legacy Forecasts are dynamic imports from Forecast Engine v1."
                  },
                  "job_id": {
                    "type": "integer",
                    "description": "The run's job."
                  },
                  "run": {
                    "type": "string",
                    "description": "The run's name, as the date it ran and a number."
                  },
                  "ran_at": {
                    "type": "string",
                    "description": "When the run was submitted.",
                    "format": "date-time"
                  },
                  "indexed_at": {
                    "type": "string",
                    "description": "On GET /plans rows: when the server last read the run into its index. A run read again, after its file changed or a read failed, has the later time. `created_from` keeps a run whose `created_at` or `indexed_at` is at or after it.",
                    "format": "date-time"
                  }
                },
                "additionalProperties": false
              }
            ],
            "description": "With `origin` on GET /plans or `include=origin`, and always on a Legacy Forecast: where the plan came from."
          },
          "streams": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A stream.",
              "enum": [
                "oil",
                "gas",
                "water"
              ]
            },
            "description": "With `origin`: the streams the plan forecast, in oil, gas, water order; its forecasts and totals carry only these. Every stream on a v2 plan."
          },
          "stream_labels": {
            "type": "object",
            "description": "With `origin`, only where a stream holds something its name doesn't say: `{\"oil\": \"condensate\"}` on a run that forecast condensate, or on a v2 plan whose model set labels its oil slot condensate.",
            "required": [],
            "properties": {
              "oil": {
                "type": "string",
                "description": "What the oil stream holds, as `condensate`."
              }
            },
            "additionalProperties": false
          },
          "timings": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PlanTimings"
              },
              {
                "type": "null"
              }
            ],
            "description": "Only with include=timings: where the plan's time went, from each finished chunk (up to 1,000 wells) and depletion chain wave pass. Null when nothing was timed: a queued plan, a Legacy Forecast or an older plan.\n\nA running plan shows the chunks finished so far, as of its server's last heartbeat (every 30 s by default) when that is another server. A resumed plan counts each finished chunk and pass as the run that finished it timed it, except an older server's."
          }
        },
        "additionalProperties": false
      },
      "PlanTimings": {
        "type": "object",
        "description": "Where a plan's time went: per worker step, the time its chunks spent there, and how long they waited for a step. A chunk's time outside these steps (finding its halo of nearby plan wells, reading its neighbours' details, storing its results) is in none.",
        "required": [
          "steps",
          "wait"
        ],
        "properties": {
          "steps": {
            "type": "object",
            "description": "The worker steps with a timed chunk, in this order.",
            "required": [],
            "properties": {
              "spacing": {
                "$ref": "#/components/schemas/PlanStepTimes",
                "description": "The TVD estimate, the subsurface grids and the spacing worker, which run while a chunk holds the spacing step."
              },
              "calc": {
                "$ref": "#/components/schemas/PlanStepTimes",
                "description": "The spacing feature worker."
              },
              "forecast": {
                "$ref": "#/components/schemas/PlanStepTimes",
                "description": "The forecast worker."
              },
              "eur": {
                "$ref": "#/components/schemas/PlanStepTimes",
                "description": "With eur: true, the EUR fits once a chunk holds the eur step."
              },
              "chain": {
                "$ref": "#/components/schemas/PlanStepTimes",
                "description": "With depletion_chain applied, each wave pass's work in its steps: the parents' extension, the production pass, the re-forecast and, with eur: true, its EUR fits. `chunks` counts passes."
              }
            },
            "additionalProperties": false
          },
          "wait": {
            "$ref": "#/components/schemas/PlanStepTimes",
            "description": "How long each timed chunk and wave pass waited to enter its steps, all of them together: for another chunk or pass to leave a step and, for spacing, for room for its wells on the server."
          }
        },
        "additionalProperties": false
      },
      "PlanStepTimes": {
        "type": "object",
        "description": "One step's timed chunks.",
        "required": [
          "chunks",
          "seconds",
          "p50_seconds",
          "max_seconds"
        ],
        "properties": {
          "chunks": {
            "type": "integer",
            "description": "Chunks timed; for chain, wave passes; for wait, both.",
            "minimum": 0
          },
          "seconds": {
            "type": "number",
            "description": "Their total, in seconds to 0.01.",
            "minimum": 0
          },
          "p50_seconds": {
            "type": "number",
            "description": "The median chunk's seconds, the lower of the two middle ones for an even count.",
            "minimum": 0
          },
          "max_seconds": {
            "type": "number",
            "description": "The longest chunk's seconds.",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "PlanDryRun": {
        "type": "object",
        "description": "POST /plans with dry_run: true: the plan a create would start, counted, with nothing started.",
        "required": [
          "dry_run",
          "wells",
          "designs",
          "forecasts"
        ],
        "properties": {
          "dry_run": {
            "const": true,
            "description": "Always true: nothing was started."
          },
          "wells": {
            "type": "integer",
            "description": "Wells the plan would have: wells as sent, or laid out from layout or layouts.",
            "minimum": 1
          },
          "designs": {
            "type": "integer",
            "description": "Completion designs the plan would run, one when none is sent.",
            "minimum": 1
          },
          "forecasts": {
            "type": "integer",
            "description": "wells × designs, what GET /dataset `limits.plan_wells` caps.",
            "minimum": 1
          },
          "scenarios": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScenarioEcho"
            },
            "description": "When the request sent scenarios: each, in the order its first well came, with its well count."
          },
          "layout": {
            "$ref": "#/components/schemas/LayoutEcho",
            "description": "When the request sent layout: what it would lay out, as the plan would echo it."
          },
          "layouts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanLayoutEcho"
            },
            "description": "When the request sent layouts: what each would lay out, in order, as the plan would echo them."
          },
          "assumption_set": {
            "$ref": "#/components/schemas/AssumptionSetEcho",
            "description": "When the request sent assumption_set: the set, as the plan would echo it."
          }
        },
        "additionalProperties": false
      },
      "PlanList": {
        "type": "object",
        "description": "Plans.",
        "required": [
          "plans",
          "next_cursor"
        ],
        "properties": {
          "plans": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Plan"
            },
            "description": "Plans, newest first."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Cursor for the next page."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Why Legacy Forecasts are missing, as a sentence a person can read."
            },
            "description": "With `origin`: empty when no Legacy Forecast the answer would hold is missing."
          },
          "warning_details": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanListWarning"
            },
            "description": "With `origin`: each warning's code and message, in `warnings`' order."
          },
          "counts": {
            "$ref": "#/components/schemas/PlanListCounts"
          },
          "facets": {
            "$ref": "#/components/schemas/PlanListFacets"
          }
        },
        "additionalProperties": false
      },
      "PlanListCounts": {
        "type": "object",
        "description": "With include=counts: `matched`, the plans that pass every filter over all pages. `cursor` and `limit` don't change it. A Legacy Forecast left out as `fe_runs_pending` isn't counted.",
        "required": [
          "matched"
        ],
        "properties": {
          "matched": {
            "type": "integer",
            "description": "The plans that pass every filter, over all pages.",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "PlanListFacets": {
        "type": "object",
        "description": "With `facets`: per field asked, its values as `{value, count}`, with `label` where the value isn't words. `count` is the plans passing every filter but this field's own.\n\n- `origin`, `status`, `saved` and `shared` list every value, 0 included.\n- `created_by`, `streams` and `month` list values at least one plan has under the other filters, plus any the request filters on.\n- A Legacy Forecast left out as `fe_runs_pending` isn't counted.",
        "required": [],
        "properties": {
          "origin": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanListFacetValue"
            },
            "description": "`v2`, then `fe`; `fe` is left out when the Legacy Forecasts can't be listed (a `fe_runs_unavailable` warning)."
          },
          "status": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanListFacetValue"
            },
            "description": "`done`, `running`, `error`."
          },
          "saved": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanListFacetValue"
            },
            "description": "`true`, `false`. A Legacy Forecast counts in neither."
          },
          "shared": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanListFacetValue"
            },
            "description": "`true` (an active share link), `false`. A Legacy Forecast counts in neither."
          },
          "created_by": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanListFacetValue"
            },
            "description": "`me` first whenever the request has a signed-in user, labelled with its email and carrying your own person key as `key`, then person keys by count, then label. Each key's `label` is its email in lower case, from every plan in the tenant whatever the other filters, so a key the request names has none only when no plan names it. Legacy Forecasts and plans that name no one count in none."
          },
          "streams": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanListFacetValue"
            },
            "description": "The sets present, by count then name, each with its name as `label`: `Oil and gas`, `Gas`, `Condensate and gas`, `Oil, gas and water`. A plan without streams counts in none."
          },
          "month": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanListFacetValue"
            },
            "description": "`YYYY-MM`, the UTC month each plan ran (the time `ran_from` reads), newest first."
          }
        },
        "additionalProperties": false
      },
      "PlanListFacetValue": {
        "type": "object",
        "description": "One facet value and its count.",
        "required": [
          "value",
          "count"
        ],
        "properties": {
          "value": {
            "type": "string",
            "description": "The value, as its filter takes it."
          },
          "count": {
            "type": "integer",
            "description": "The plans passing every filter but this field's own.",
            "minimum": 0
          },
          "label": {
            "type": "string",
            "description": "Only where the value isn't words: the email behind `me` or a person key, or a `streams` set's name."
          },
          "key": {
            "type": "string",
            "description": "On `created_by`'s `me` only: your own person key. GET /plans reads it as `me`, so a client shows a saved filter naming it as you.",
            "pattern": "^u_[0-9a-f]{16}$"
          }
        },
        "additionalProperties": false
      },
      "PlanListWarning": {
        "type": "object",
        "description": "A list warning and its code.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Why Legacy Forecasts are missing.\n\n- `fe_runs_unavailable`: they can't be listed, so the answer holds only v2 plans (`origin=fe` answers 503 instead).\n- `fe_runs_pending`: runs not yet read are left out and counted. With `created_from`, each is in the first later answer whose `created_from` is at or before the time it is read; without it, list again shortly, from the first page.",
            "enum": [
              "fe_runs_unavailable",
              "fe_runs_pending"
            ]
          },
          "message": {
            "type": "string",
            "description": "The warning as `warnings` holds it, a sentence without codes or routes."
          }
        },
        "additionalProperties": false
      },
      "DeletedPlan": {
        "type": "object",
        "description": "Deleted plan.",
        "required": [
          "id",
          "deleted"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Plan id.",
            "format": "uuid"
          },
          "deleted": {
            "const": true,
            "description": "Always true."
          }
        },
        "additionalProperties": false
      },
      "DeletedPlans": {
        "type": "object",
        "description": "Unfinished plans deleted.",
        "required": [
          "deleted",
          "kept",
          "remaining",
          "ids"
        ],
        "properties": {
          "deleted": {
            "type": "integer",
            "description": "Plans deleted by this call: `ids` counted.",
            "minimum": 0
          },
          "kept": {
            "type": "integer",
            "description": "Matching plans left because they are saved or shared.",
            "minimum": 0
          },
          "remaining": {
            "type": "integer",
            "description": "Matching plans not deleted: past the 200 one call deletes, or whose delete failed. Call again until it is 0.",
            "minimum": 0
          },
          "ids": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Plan id.",
              "format": "uuid"
            },
            "description": "The deleted plans, newest first.",
            "maxItems": 200
          }
        },
        "additionalProperties": false
      },
      "PlanChecks": {
        "type": "object",
        "description": "Plan checks rollup.",
        "required": [
          "plan_id",
          "status",
          "checks"
        ],
        "properties": {
          "plan_id": {
            "type": "string",
            "description": "Plan id.",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "description": "Plan status.",
            "enum": [
              "running",
              "done",
              "error"
            ]
          },
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanChecksEntry"
            },
            "description": "One entry per scenario and design."
          }
        },
        "additionalProperties": false
      },
      "PlanChecksEntry": {
        "type": "object",
        "description": "Checks for one design and scenario.",
        "required": [
          "design",
          "wells",
          "wells_checked",
          "wells_flagged",
          "wells_unchecked",
          "out_of_range",
          "missing",
          "unknown_formation",
          "context"
        ],
        "properties": {
          "design": {
            "type": "integer",
            "description": "The design, as its index in `designs`.",
            "minimum": 0
          },
          "scenario": {
            "type": "string",
            "description": "Scenario name, only on scenario plans."
          },
          "wells": {
            "type": "integer",
            "description": "All wells in scope, including failed wells.",
            "minimum": 0
          },
          "wells_checked": {
            "type": "integer",
            "description": "Wells with available checks.",
            "minimum": 0
          },
          "wells_flagged": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Checked wells with flagged; null when no well was checked, as in totals.",
            "minimum": 0
          },
          "wells_context": {
            "type": "integer",
            "description": "Checked wells with context, absent when none, as in totals; context flags nothing.",
            "minimum": 1
          },
          "wells_unchecked": {
            "type": "integer",
            "description": "Wells with held forecasts but no available checks.",
            "minimum": 0
          },
          "out_of_range": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanCheckRow"
            },
            "description": "Inputs outside training."
          },
          "missing": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanMissingRow"
            },
            "description": "Missing inputs."
          },
          "unknown_formation": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanFormationRow"
            },
            "description": "Formations absent from training."
          },
          "context": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanCheckRow"
            },
            "description": "Neighboring production outside training; flags nothing."
          }
        },
        "additionalProperties": false
      },
      "PlanCheckRow": {
        "type": "object",
        "description": "Wells outside one input range on one side for one model.",
        "required": [
          "feature",
          "side",
          "wells",
          "low",
          "high",
          "min",
          "max",
          "model_num",
          "well_indexes"
        ],
        "properties": {
          "feature": {
            "type": "string",
            "description": "Input name; labels come from GET /models inputs[].label."
          },
          "side": {
            "type": "string",
            "description": "Below or above the training range p01..p99.",
            "enum": [
              "below",
              "above"
            ]
          },
          "wells": {
            "type": "integer",
            "description": "Distinct wells counted.",
            "minimum": 1
          },
          "low": {
            "type": "number",
            "description": "Training p01 from the first counted item."
          },
          "high": {
            "type": "number",
            "description": "Training p99 from the first counted item."
          },
          "min": {
            "type": "number",
            "description": "Smallest counted value."
          },
          "max": {
            "type": "number",
            "description": "Largest counted value."
          },
          "model_num": {
            "type": "string",
            "description": "Model supplying the training range."
          },
          "well_indexes": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "Plan well index.",
              "minimum": 0
            },
            "description": "First 20 counted wells in plan order.",
            "maxItems": 20
          }
        },
        "additionalProperties": false
      },
      "PlanMissingRow": {
        "type": "object",
        "description": "Wells missing one input.",
        "required": [
          "feature",
          "wells",
          "well_indexes"
        ],
        "properties": {
          "feature": {
            "type": "string",
            "description": "Missing input name."
          },
          "wells": {
            "type": "integer",
            "description": "Distinct wells counted.",
            "minimum": 1
          },
          "well_indexes": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "Plan well index.",
              "minimum": 0
            },
            "description": "First 20 counted wells in plan order.",
            "maxItems": 20
          }
        },
        "additionalProperties": false
      },
      "PlanFormationRow": {
        "type": "object",
        "description": "Wells with one unknown formation.",
        "required": [
          "value",
          "wells",
          "well_indexes"
        ],
        "properties": {
          "value": {
            "type": "string",
            "description": "Formation absent from training."
          },
          "wells": {
            "type": "integer",
            "description": "Distinct wells counted.",
            "minimum": 1
          },
          "well_indexes": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "Plan well index.",
              "minimum": 0
            },
            "description": "First 20 counted wells in plan order.",
            "maxItems": 20
          }
        },
        "additionalProperties": false
      },
      "PlanRollup": {
        "type": "object",
        "description": "A plan's oil, gas and water at one ip_day, summed by pad and by formation inside each pad.",
        "required": [
          "plan_id",
          "design",
          "scenario",
          "ip_day",
          "partial",
          "units",
          "totals",
          "pads"
        ],
        "properties": {
          "plan_id": {
            "type": "string",
            "description": "Plan id.",
            "format": "uuid"
          },
          "design": {
            "type": "integer",
            "description": "The design, as its index in `designs`.",
            "minimum": 0
          },
          "scenario": {
            "type": [
              "string",
              "null"
            ],
            "description": "The scenario summed; null on a plan without scenarios."
          },
          "ip_day": {
            "type": "integer",
            "description": "The ip_day (days since first production) each cumulative volume is read at.",
            "minimum": 1
          },
          "partial": {
            "type": "boolean",
            "description": "True while the plan runs: counts and sums cover the wells finished so far, and every row is listed."
          },
          "units": {
            "type": "object",
            "description": "The unit of each stream's value.",
            "required": [
              "oil",
              "gas",
              "water"
            ],
            "properties": {
              "oil": {
                "type": "string",
                "description": "Oil volume unit.",
                "enum": [
                  "bbl"
                ]
              },
              "gas": {
                "type": "string",
                "description": "Gas volume unit.",
                "enum": [
                  "mcf"
                ]
              },
              "water": {
                "type": "string",
                "description": "Water volume unit.",
                "enum": [
                  "bbl"
                ]
              }
            },
            "additionalProperties": false
          },
          "totals": {
            "$ref": "#/components/schemas/PlanRollupRow",
            "description": "Every well in scope. On a done plan it equals GET /plans/{id} totals for this design and scenario at ip_day."
          },
          "pads": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanRollupPad"
            },
            "description": "Every pad, in plan order of each pad's first well, wells without a pad last."
          }
        },
        "additionalProperties": false
      },
      "PlanRollupRow": {
        "type": "object",
        "description": "Counts and sums over a group of wells. Only the streams the model set serves (GET /model-sets `streams`): a set serving gas alone answers gas alone.",
        "required": [
          "wells",
          "wells_with_forecast",
          "wells_flagged"
        ],
        "properties": {
          "wells": {
            "type": "integer",
            "description": "Wells in the group and scope, forecast or not, finished or not.",
            "minimum": 0
          },
          "wells_with_forecast": {
            "type": "integer",
            "description": "Wells with a forecast under the design, as GET /plans/{id} totals counts them; while running, of those finished.",
            "minimum": 0
          },
          "wells_flagged": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Wells whose checks flagged inputs outside training, as totals counts them; null when no well in the row was checked.",
            "minimum": 0
          },
          "oil": {
            "$ref": "#/components/schemas/PlanRollupStream"
          },
          "gas": {
            "$ref": "#/components/schemas/PlanRollupStream"
          },
          "water": {
            "$ref": "#/components/schemas/PlanRollupStream"
          },
          "eur": {
            "$ref": "#/components/schemas/PlanRollupEur"
          }
        },
        "additionalProperties": false
      },
      "PlanRollupStream": {
        "type": "object",
        "description": "One stream's sum.",
        "required": [
          "value",
          "wells"
        ],
        "properties": {
          "value": {
            "type": [
              "number",
              "null"
            ],
            "description": "The cumulative volume at ip_day summed over `wells`, in `units`, rounded once to 0.1; null when `wells` is 0."
          },
          "wells": {
            "type": "integer",
            "description": "Wells summed: those with this stream's forecast.",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "PlanRollupPad": {
        "type": "object",
        "description": "A pad's roll-up.",
        "required": [
          "key",
          "wells",
          "wells_with_forecast",
          "wells_flagged",
          "formations"
        ],
        "properties": {
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "The pad key the plan was sent; null for wells without one."
          },
          "name": {
            "type": "string",
            "description": "The pad's name, only when the plan names it."
          },
          "wells": {
            "type": "integer",
            "description": "Wells in the group and scope, forecast or not, finished or not.",
            "minimum": 0
          },
          "wells_with_forecast": {
            "type": "integer",
            "description": "Wells with a forecast under the design, as GET /plans/{id} totals counts them; while running, of those finished.",
            "minimum": 0
          },
          "wells_flagged": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Wells whose checks flagged inputs outside training, as totals counts them; null when no well in the row was checked.",
            "minimum": 0
          },
          "oil": {
            "$ref": "#/components/schemas/PlanRollupStream"
          },
          "gas": {
            "$ref": "#/components/schemas/PlanRollupStream"
          },
          "water": {
            "$ref": "#/components/schemas/PlanRollupStream"
          },
          "eur": {
            "$ref": "#/components/schemas/PlanRollupEur"
          },
          "formations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanRollupFormation"
            },
            "description": "The pad's wells by formation: GET /formations order, unlisted ones by name, wells without one last."
          }
        },
        "additionalProperties": false
      },
      "PlanRollupFormation": {
        "type": "object",
        "description": "A formation's roll-up inside one pad.",
        "required": [
          "key",
          "wells",
          "wells_with_forecast",
          "wells_flagged"
        ],
        "properties": {
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "The formation; null for wells without one."
          },
          "wells": {
            "type": "integer",
            "description": "Wells in the group and scope, forecast or not, finished or not.",
            "minimum": 0
          },
          "wells_with_forecast": {
            "type": "integer",
            "description": "Wells with a forecast under the design, as GET /plans/{id} totals counts them; while running, of those finished.",
            "minimum": 0
          },
          "wells_flagged": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Wells whose checks flagged inputs outside training, as totals counts them; null when no well in the row was checked.",
            "minimum": 0
          },
          "oil": {
            "$ref": "#/components/schemas/PlanRollupStream"
          },
          "gas": {
            "$ref": "#/components/schemas/PlanRollupStream"
          },
          "water": {
            "$ref": "#/components/schemas/PlanRollupStream"
          },
          "eur": {
            "$ref": "#/components/schemas/PlanRollupEur"
          }
        },
        "additionalProperties": false
      },
      "PlanRollupEur": {
        "type": "object",
        "description": "On a plan made with eur: true: each stream's EUR summed over the row's wells with one, and BOE over those with both, by the code GET /plans/{id} totals `eur` uses; no P10 or P90. Only the streams the model set serves (GET /model-sets `streams`): a set serving gas alone answers gas alone.",
        "required": [
          "boe"
        ],
        "properties": {
          "oil": {
            "$ref": "#/components/schemas/PlanRollupEurStream"
          },
          "gas": {
            "$ref": "#/components/schemas/PlanRollupEurStream"
          },
          "water": {
            "$ref": "#/components/schemas/PlanRollupEurStream",
            "description": "Only on a plan made with eur_water: true. BOE doesn't read it."
          },
          "boe": {
            "type": "object",
            "description": "BOE EUR over the wells with both fits, so the sum and the well count agree.",
            "required": [
              "value",
              "wells"
            ],
            "properties": {
              "value": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Oil EUR plus gas EUR / 6 (bbl of oil equivalent) summed over the wells with both; null when none has."
              },
              "wells": {
                "type": "integer",
                "description": "Wells with both an oil and a gas EUR."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "PlanRollupEurStream": {
        "type": "object",
        "description": "A stream's EUR over the row's wells.",
        "required": [
          "value",
          "days",
          "wells"
        ],
        "properties": {
          "value": {
            "type": [
              "number",
              "null"
            ],
            "description": "EUR summed over the wells with one; null when none has."
          },
          "days": {
            "type": [
              "integer",
              "null"
            ],
            "description": "ip_day of the EUR; null when none has one, or when the wells summed differ in eur_years: the sum then runs to no one day, and each scenario is read apart."
          },
          "wells": {
            "type": "integer",
            "description": "Wells with an EUR."
          }
        },
        "additionalProperties": false
      },
      "PlanCurves": {
        "type": "object",
        "description": "A page of a plan's well curves.",
        "required": [
          "plan_id",
          "design",
          "step_days",
          "streams",
          "p_levels",
          "wells",
          "next_cursor"
        ],
        "properties": {
          "plan_id": {
            "type": "string",
            "description": "Plan id.",
            "format": "uuid"
          },
          "design": {
            "type": "integer",
            "description": "The design, as its index in `designs`.",
            "minimum": 0
          },
          "step_days": {
            "type": "integer",
            "description": "Days between points: 30.",
            "enum": [
              30
            ]
          },
          "streams": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A stream.",
              "enum": [
                "oil",
                "gas",
                "water"
              ]
            },
            "description": "The streams read, in oil, gas, water order."
          },
          "stream_labels": {
            "type": "object",
            "description": "Only when a stream holds another product: condensate in the oil stream.",
            "required": [],
            "properties": {
              "oil": {
                "type": "string",
                "description": "What the oil stream holds.",
                "enum": [
                  "condensate"
                ]
              }
            },
            "additionalProperties": false
          },
          "p_levels": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A P-level.",
              "enum": [
                "P50",
                "P10",
                "P90"
              ]
            },
            "description": "The P-levels read, in P50, P10, P90 order."
          },
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanCurvesWell"
            },
            "description": "The page's wells, in plan order."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as `cursor` for the next page; null on the last."
          },
          "plan_day": {
            "type": "string",
            "description": "Only with start_date: the plan's day, fixed when the plan was made. A Legacy Forecast's day is its run date, else its results file's date. With start_date=til, a well without a TIL date starts on it.",
            "format": "date"
          }
        },
        "additionalProperties": false
      },
      "PlanCurvesWell": {
        "type": "object",
        "description": "A well's curves, or why it has none.",
        "required": [
          "index",
          "key",
          "well_uid",
          "label"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "Plan well index.",
            "minimum": 0
          },
          "key": {
            "type": "string",
            "description": "The well's key, unique within this plan only."
          },
          "well_uid": {
            "type": "string",
            "description": "The well's id across plans: the first 32 lowercase hex characters of the SHA-256 of the UTF-8 string `<plan_id>:<key>`. 32 characters, the same on every read of the plan. A plan run again (from_plan) has a new id, so its wells get new ones.",
            "pattern": "^[0-9a-f]{32}$"
          },
          "label": {
            "type": "string",
            "description": "Plan well N."
          },
          "name": {
            "type": "string",
            "description": "Only when the well has a name."
          },
          "til_date": {
            "type": "string",
            "description": "Only when the well has a TIL date.",
            "format": "date"
          },
          "shl": {
            "type": "array",
            "description": "Surface hole location, [lng, lat], as the well's `include=wells` inputs give it. Left out when the well has no inputs.",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "heel": {
            "type": "array",
            "description": "Heel, [lng, lat], as the well's `include=wells` inputs give it. Only when the well has one.",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "bhl": {
            "type": "array",
            "description": "Bottom hole (toe) location, [lng, lat], as the well's `include=wells` inputs give it. Left out when the well has no inputs.",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "scenario": {
            "type": "string",
            "description": "The well's scenario, only on a plan made with scenarios."
          },
          "curves": {
            "type": "object",
            "description": "Each stream read.",
            "required": [],
            "properties": {
              "oil": {
                "$ref": "#/components/schemas/PlanCurveStream"
              },
              "gas": {
                "$ref": "#/components/schemas/PlanCurveStream"
              },
              "water": {
                "$ref": "#/components/schemas/PlanCurveStream"
              }
            },
            "additionalProperties": false
          },
          "start_date": {
            "type": "string",
            "description": "Only with start_date: the day this well's calendar months are counted from.",
            "format": "date"
          },
          "start_date_source": {
            "type": "string",
            "description": "Only with start_date: til (its TIL date), plan_day (it has none, so the plan's day) or request (start_date named the day).",
            "enum": [
              "til",
              "plan_day",
              "request"
            ]
          },
          "error": {
            "type": "string",
            "description": "Why the well has no curves: it couldn't be placed, or has no forecast for the design."
          }
        },
        "additionalProperties": false
      },
      "PlanCurveStream": {
        "description": "One stream's curves, or why it has none.",
        "oneOf": [
          {
            "type": "object",
            "description": "Each P-level read.",
            "required": [
              "unit"
            ],
            "properties": {
              "unit": {
                "type": "string",
                "description": "Volume unit: bbl for oil and water, mcf for gas.",
                "enum": [
                  "bbl",
                  "mcf"
                ]
              },
              "P50": {
                "$ref": "#/components/schemas/PlanCurve"
              },
              "P10": {
                "$ref": "#/components/schemas/PlanCurve"
              },
              "P90": {
                "$ref": "#/components/schemas/PlanCurve"
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No curves.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why the stream failed."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "PlanCurve": {
        "description": "One curve, or why the well has none at this P-level.",
        "oneOf": [
          {
            "type": "object",
            "description": "A curve.",
            "required": [
              "cum",
              "model_months",
              "extension",
              "note"
            ],
            "properties": {
              "cum": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Cumulative volume at day 30·m, to 0.01."
                },
                "description": "`cum[m-1]` is the cumulative at day 30·m; null where the month has no value."
              },
              "model_months": {
                "type": "integer",
                "description": "Months from the model; the rest come from the extension.",
                "minimum": 0
              },
              "extension": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The extension's kind, or null when the curve has none.",
                "enum": [
                  "arps",
                  "flat",
                  "table",
                  null
                ]
              },
              "note": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Why there is no extension; null with one."
              },
              "calendar": {
                "type": "object",
                "description": "Only with start_date: the curve's volume by calendar month.",
                "required": [
                  "first_month",
                  "volumes"
                ],
                "properties": {
                  "first_month": {
                    "type": "string",
                    "description": "The start date's month, as YYYY-MM.",
                    "pattern": "^\\d{4}-\\d{2}$"
                  },
                  "volumes": {
                    "type": "array",
                    "items": {
                      "type": "number",
                      "description": "The volume in the month, to 0.01."
                    },
                    "description": "One per calendar month from first_month: the first from the start date, the last the month that holds the curve's last point."
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No curve.",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string",
                "description": "Why the well has no curve at this P-level."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "PlanStats": {
        "type": "object",
        "description": "The distribution of a per-well metric over a plan's wells.",
        "required": [
          "id",
          "design",
          "metric",
          "ip_day",
          "unit",
          "partial",
          "wells",
          "missing",
          "min",
          "max",
          "mean",
          "quantiles",
          "histogram"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Plan id.",
            "format": "uuid"
          },
          "design": {
            "type": "integer",
            "description": "The design, as its index in `designs`.",
            "minimum": 0
          },
          "metric": {
            "type": "string",
            "description": "The metric measured.",
            "enum": [
              "eur_boe",
              "eur_oil",
              "eur_gas",
              "cum_boe",
              "cum_oil",
              "cum_gas"
            ]
          },
          "ip_day": {
            "type": [
              "integer",
              "null"
            ],
            "description": "For a cum_ metric, the ip_day measured; null for an eur_ metric."
          },
          "unit": {
            "type": "string",
            "description": "The unit of every value: bbl (oil), mcf (gas) or BOE.",
            "enum": [
              "bbl",
              "mcf",
              "BOE"
            ]
          },
          "partial": {
            "type": "boolean",
            "description": "True while the plan runs: the figures cover the wells finished so far."
          },
          "wells": {
            "type": "integer",
            "description": "Wells with a value; every figure describes them.",
            "minimum": 0
          },
          "missing": {
            "type": "integer",
            "description": "Wells finished without a value: no forecast, a failed EUR fit, or BOE without both oil and gas.",
            "minimum": 0
          },
          "min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Smallest value; null when no well has one."
          },
          "max": {
            "type": [
              "number",
              "null"
            ],
            "description": "Largest value; null when no well has one."
          },
          "mean": {
            "type": [
              "number",
              "null"
            ],
            "description": "Mean value; null when no well has one."
          },
          "quantiles": {
            "type": "object",
            "description": "Quantiles across wells (linear interpolation between the closest ranks), not P-level bands: q10 (the 10th percentile of the wells' values, the low end), q50 (the median) and q90 (the high end), or with quantiles= exactly the asked ones; each null when no well has a value.",
            "patternProperties": {
              "^q([1-9]|[1-9][0-9])$": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "additionalProperties": false
          },
          "histogram": {
            "type": "object",
            "description": "Equal-width bins from min to max.",
            "required": [
              "edges",
              "counts"
            ],
            "properties": {
              "edges": {
                "type": "array",
                "items": {
                  "type": "number",
                  "description": "A bin edge."
                },
                "description": "Bin edges, ascending, one more than counts; empty when no well has a value."
              },
              "counts": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "description": "Wells in the bin.",
                  "minimum": 0
                },
                "description": "Wells per bin; they add up to wells."
              }
            },
            "additionalProperties": false
          },
          "normalize_lateral_ft": {
            "type": "number",
            "description": "With normalize_lateral_ft: the lateral every value was scaled to, ft."
          },
          "scenario": {
            "type": "string",
            "description": "With scenario: the scenario measured."
          },
          "values": {
            "$ref": "#/components/schemas/PlanStatsValues",
            "description": "With include=values: every well with a value, ascending."
          },
          "group_by": {
            "type": "string",
            "description": "With group_by: what groups is by.",
            "enum": [
              "design",
              "formation",
              "scenario",
              "pad"
            ]
          },
          "groups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanStatsGroup"
            },
            "description": "With group_by: each design in order, each formation in GET /formations order, then wells without one, or each scenario in the order of the plan's `scenarios`; pad lists all keys in first measured well order, null last, never folded into Other. For other groupings, at most 50, the rest in one Other row."
          }
        },
        "additionalProperties": false
      },
      "PdpScope": {
        "type": "object",
        "description": "What the rule measured from. center is the section line's center: center as sent, else the mean of the scope wells' lateral midpoints to 1e-7°, as POST /gun-barrels gives it; with cross, the mean of A and B to 1e-7°.\n\nradius_mi, and each distance_ft without reach, are measured from that mean, unrounded; with reach=laterals, distance_ft is the gap to the nearest scope well's lateral.",
        "required": [
          "indexes",
          "center",
          "radius_mi",
          "azimuth_deg",
          "til_date",
          "margin_mi",
          "parallel_deg"
        ],
        "properties": {
          "indexes": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "A plan well index.",
              "minimum": 0
            },
            "description": "The plan wells measured from, ascending: `wells` as sent, else every well. POST /pdp-wells: every sent well's position in `wells`, 0 to n-1."
          },
          "center": {
            "$ref": "#/components/schemas/LngLat"
          },
          "radius_mi": {
            "type": "number",
            "description": "How far from the scope wells' mean midpoint candidates were looked for, mi (not from a sent center): the farthest scope well midpoint plus margin_mi, rounded to 0.01. With reach=laterals it is still given, but picks no well. With cross: from the mean of A and B, half A-B plus 25,000 ft, rounded to 0.01.",
            "exclusiveMinimum": 0
          },
          "azimuth_deg": {
            "type": "number",
            "description": "The section line's azimuth, degrees clockwise from north in [0, 360): azimuth_deg as sent (brought into that range), else the scope wells' mean heel-to-toe direction to 0.1, as POST /gun-barrels gives it for them. With cross: square to A-B, A-B's bearing less 90, to 0.1.",
            "minimum": 0,
            "exclusiveMaximum": 360
          },
          "til_date": {
            "type": "string",
            "description": "The earliest TIL date of the scope wells: kept wells first produced on or before it.",
            "format": "date"
          },
          "margin_mi": {
            "type": "number",
            "description": "The margin added to the radius, mi; with reach=laterals, also how far from any scope well's lateral a kept lateral may lie.",
            "const": 0.5
          },
          "parallel_deg": {
            "type": "number",
            "description": "How far a kept lateral may turn from the line, either way along it, degrees.",
            "const": 15
          },
          "cross": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LngLat"
            },
            "description": "With cross: A and B, as sent.",
            "minItems": 2,
            "maxItems": 2
          },
          "reach": {
            "type": "string",
            "description": "With reach=laterals: laterals.",
            "enum": [
              "laterals"
            ]
          },
          "along": {
            "type": "string",
            "description": "With along=section: section.",
            "enum": [
              "section"
            ]
          },
          "along_range_ft": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "ft along the section line from center, + in the direction of azimuth_deg."
            },
            "description": "With along=section: [from, to], the scope wells' heel-to-toe range on the line; a kept lateral overlaps it.",
            "minItems": 2,
            "maxItems": 2
          }
        },
        "additionalProperties": false
      },
      "PdpWell": {
        "type": "object",
        "description": "An existing well producing by the TIL date.",
        "required": [
          "wellbore_key",
          "well_name",
          "operator",
          "formation",
          "first_prod",
          "lateral_length_ft",
          "distance_ft"
        ],
        "properties": {
          "wellbore_key": {
            "type": "string",
            "description": "Wellbore key, as GET /wells lists it."
          },
          "well_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Well name."
          },
          "operator": {
            "type": [
              "string",
              "null"
            ],
            "description": "Operator."
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Landing formation."
          },
          "first_prod": {
            "type": "string",
            "description": "First production, YYYY-MM-DD: on or before scope.til_date.",
            "format": "date"
          },
          "lateral_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Lateral length, ft, as GET /wells `lateral_length`: to normalise its production per 1,000 ft."
          },
          "distance_ft": {
            "type": "integer",
            "description": "From the scope wells' mean midpoint (unrounded; scope.center without a sent center) to its lateral midpoint, ft, as GET /wells `near` measures it, rounded. With reach=laterals: the gap from its lateral to the nearest scope well's lateral, ft, rounded. With cross: from the mean of A and B (unrounded) to its lateral midpoint, ft, rounded.",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "PlanPdpWells": {
        "type": "object",
        "description": "A plan's PDP wells by the gun barrel's rule, or drawn wells' (POST /pdp-wells).",
        "required": [
          "scope",
          "matched",
          "wells"
        ],
        "properties": {
          "scope": {
            "$ref": "#/components/schemas/PdpScope"
          },
          "matched": {
            "type": "integer",
            "description": "Wells that passed every cut, before limit.",
            "minimum": 0
          },
          "left_out": {
            "type": "object",
            "description": "With include=left_out: the wells the TIL date and limit leave out.",
            "required": [
              "til_date",
              "limit"
            ],
            "properties": {
              "til_date": {
                "type": "integer",
                "description": "Wells that passed every other cut but first produced after scope.til_date or have no first production.",
                "minimum": 0
              },
              "limit": {
                "type": "integer",
                "description": "Wells past limit: matched less the wells returned.",
                "minimum": 0
              }
            },
            "additionalProperties": false
          },
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PdpWell"
            },
            "description": "The nearest `limit` of them, nearest first, ties by wellbore key.",
            "maxItems": 50
          }
        },
        "additionalProperties": false
      },
      "PdpWellsRequest": {
        "type": "object",
        "description": "Drawn wells and the options GET /plans/{id}/pdp-wells takes.",
        "required": [
          "wells"
        ],
        "properties": {
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WellInput"
            },
            "description": "Drawn wells, as POST /gun-barrels takes them: fluid_bbl_per_ft, proppant_lb_per_ft, decline or name is a 400. Each well's til_date dates it; a well without one comes online today (UTC).",
            "minItems": 1,
            "maxItems": 500
          },
          "azimuth_deg": {
            "type": "number",
            "description": "The section line's azimuth, as GET /plans/{id}/pdp-wells takes it: degrees clockwise from north, -360 to 360, brought into [0, 360). Absent: the wells' mean heel-to-toe direction to 0.1°.",
            "minimum": -360,
            "maximum": 360
          },
          "center": {
            "$ref": "#/components/schemas/LngLat",
            "description": "The section line's center, as GET /plans/{id}/pdp-wells takes `center`: it moves no candidate. Absent: the wells' mean midpoint, to 1e-7°."
          },
          "along": {
            "type": "string",
            "description": "`section`: keep only wells whose lateral overlaps the wells' heel-to-toe range along the section line, as GET /plans/{id}/pdp-wells does. Absent: no such cut.",
            "enum": [
              "section"
            ]
          },
          "limit": {
            "type": "integer",
            "description": "The most wells to return, nearest first: 1 to 50. `matched` still counts them all.",
            "minimum": 1,
            "maximum": 50,
            "default": 50
          },
          "reach": {
            "type": "string",
            "description": "`laterals`: candidates are the wells with any part of their lateral within margin_mi of any sent well's lateral, as GET /plans/{id}/pdp-wells takes `reach`. Absent: the circle around the midpoints.",
            "enum": [
              "laterals"
            ]
          },
          "cross": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LngLat"
            },
            "description": "A line A-B drawn across the laterals, [A, B]: the wells whose laterals cross A-B, as GET /plans/{id}/pdp-wells takes `cross`; the sent wells only date them. Not with azimuth_deg, center, along or reach. Absent: the circle around the midpoints.",
            "minItems": 2,
            "maxItems": 2
          },
          "include": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "left_out: how many wells the TIL date and limit leave out.",
              "enum": [
                "left_out"
              ]
            },
            "description": "Optional: left_out adds left_out, as GET /plans/{id}/pdp-wells' include=left_out.",
            "maxItems": 1,
            "uniqueItems": true
          }
        },
        "additionalProperties": false
      },
      "PlanStatsValues": {
        "type": "object",
        "description": "Every well with a value, ascending: for a probit plot, and to link a point to its well.",
        "required": [
          "index",
          "value"
        ],
        "properties": {
          "index": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "A plan well index from 0.",
              "minimum": 0
            },
            "description": "The wells, by plan index, in value order."
          },
          "value": {
            "type": "array",
            "items": {
              "type": "number",
              "description": "A value, rounded to 0.1, in unit."
            },
            "description": "Their values, ascending (ties by index)."
          }
        },
        "additionalProperties": false
      },
      "PlanStatsGroup": {
        "type": "object",
        "description": "One group's distribution.",
        "required": [
          "key",
          "wells",
          "missing",
          "min",
          "max",
          "mean",
          "quantiles",
          "histogram"
        ],
        "properties": {
          "key": {
            "type": [
              "string",
              "integer",
              "null"
            ],
            "description": "The design's index (group_by=design), the formation, null for wells without one, the scenario, the pad key (null for wells without one), or Other on the summed row. Pads never fold into Other."
          },
          "name": {
            "type": "string",
            "description": "With group_by=pad, the pad's name when the plan gives one in `pads[].name`; absent otherwise. `key` stays the pad key."
          },
          "wells": {
            "type": "integer",
            "description": "Wells in the group with a value.",
            "minimum": 0
          },
          "missing": {
            "type": "integer",
            "description": "Wells in the group without one.",
            "minimum": 0
          },
          "min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Smallest value; null when none has one."
          },
          "max": {
            "type": [
              "number",
              "null"
            ],
            "description": "Largest value; null when none has one."
          },
          "mean": {
            "type": [
              "number",
              "null"
            ],
            "description": "Mean value; null when none has one."
          },
          "quantiles": {
            "type": "object",
            "description": "The same quantiles as the top level, over this group's wells.",
            "patternProperties": {
              "^q([1-9]|[1-9][0-9])$": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "additionalProperties": false
          },
          "histogram": {
            "type": "object",
            "description": "Counts on edges every group shares, so groups plot side by side.",
            "required": [
              "edges",
              "counts"
            ],
            "properties": {
              "edges": {
                "type": "array",
                "items": {
                  "type": "number",
                  "description": "A bin edge."
                },
                "description": "The same for every group: bins bins from the smallest to the largest value of all the groups (for group_by=formation or scenario, the top-level edges); empty when no group has a value."
              },
              "counts": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "description": "Wells in the bin.",
                  "minimum": 0
                },
                "description": "This group's wells per bin; they add up to its wells."
              }
            },
            "additionalProperties": false
          },
          "values": {
            "$ref": "#/components/schemas/PlanStatsValues",
            "description": "With include=values: this group's wells, ascending."
          },
          "others": {
            "type": "integer",
            "description": "On the Other row only: how many groups it sums.",
            "minimum": 1
          }
        },
        "additionalProperties": false
      },
      "ComparisonSide": {
        "type": "object",
        "description": "One side: a plan's wells under one design, or one scenario's.",
        "required": [
          "plan"
        ],
        "properties": {
          "plan": {
            "type": "string",
            "description": "A done plan's id, as POST /plans returns it.",
            "format": "uuid"
          },
          "scenario": {
            "type": "string",
            "description": "On a plan made with scenarios, the scenario to compare, exactly as its `scenarios` list it; required there, and a 400 on a plan without scenarios. A name it doesn't have is a 400 whose `details.scenarios` lists them.",
            "minLength": 1,
            "maxLength": 60
          },
          "design": {
            "type": "integer",
            "description": "The design, as its index in the plan's `designs`; 0 by default. One past the last is a 400.",
            "minimum": 0,
            "default": 0
          }
        },
        "additionalProperties": false
      },
      "ComparisonSourceSide": {
        "type": "object",
        "description": "A forecast source as one side; the other side is a plan. Any other field is a 400 listing these.",
        "required": [
          "source"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "A forecast source's id, as POST /forecast-sources returns it; one you can read.",
            "format": "uuid"
          },
          "reserves_category": {
            "type": "string",
            "description": "The reserves category to compare, exactly as GET /forecast-sources/{id} `reserves_categories` lists it; required when the source holds more than one.",
            "minLength": 1
          }
        },
        "additionalProperties": false
      },
      "ComparisonRequest": {
        "type": "object",
        "description": "Two sides to compare. Any other field, here or in a side, is a 400 listing the allowed ones.",
        "required": [
          "a",
          "b"
        ],
        "properties": {
          "a": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ComparisonSide"
              },
              {
                "$ref": "#/components/schemas/ComparisonSourceSide"
              }
            ],
            "description": "Side a, the base: `delta` is b − a and `delta_pct` is relative to it. A plan side, or a forecast source side when side b is a plan."
          },
          "b": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ComparisonSide"
              },
              {
                "$ref": "#/components/schemas/ComparisonSourceSide"
              }
            ],
            "description": "Side b. It may be the plan of side a, with another scenario or design, or a forecast source when side a is a plan."
          },
          "metric": {
            "type": "string",
            "description": "The per-well metric distribution, groups and curves measure: eur_boe by default when both sides have EUR, else cum_boe.\n\nPer-well metrics: `eur_oil` (bbl), `eur_gas` (mcf) and `eur_boe` (BOE) are each well's EUR and need a plan made with `eur: true` (400 otherwise); `cum_oil`, `cum_gas` and `cum_boe` are the forecast's cumulative volume at `ip_day`. BOE is oil + gas / 6, only for wells with both.",
            "enum": [
              "eur_boe",
              "eur_oil",
              "eur_gas",
              "cum_boe",
              "cum_oil",
              "cum_gas"
            ]
          },
          "ip_day": {
            "type": "integer",
            "description": "For a cum_ metric, the ip_day to measure, one of the forecast ip_days GET /dataset lists; 1080 by default. With an eur_ metric it is a 400.",
            "minimum": 1
          },
          "normalize_lateral_ft": {
            "type": "number",
            "description": "Scale each well's value to this lateral length in distribution and groups, as GET /plans/{id}/stats does: value × normalize_lateral_ft / its lateral_length_ft. Totals and curves stay unscaled. 100 to 20,000.",
            "minimum": 100,
            "maximum": 20000
          },
          "group_by": {
            "type": "string",
            "description": "Also compare each group of wells: design (every design index either side has), formation (each well's target formation, null for none), scenario (a 400 when neither side's plan has scenarios), or pad (the pad key, null for wells without one; 400 when neither plan has keys). Pads pair by key in side a plan order then new side b keys, null last, without a cap or Other row.",
            "enum": [
              "design",
              "formation",
              "scenario",
              "pad"
            ]
          },
          "include": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "curves: each side's summed curve for the metric's stream; bands: with curves, each side's summed P10 and P90 (a 400 without curves); wells: paired wells' rows and their summary; inputs: the inputs that changed between paired wells; value: each side priced, and the difference.",
              "enum": [
                "curves",
                "bands",
                "wells",
                "inputs",
                "value"
              ]
            },
            "description": "Optional parts. Any other value is a 400 listing these."
          },
          "pair": {
            "$ref": "#/components/schemas/ComparisonPairing"
          },
          "wells": {
            "$ref": "#/components/schemas/ComparisonWellsPage"
          },
          "horizon": {
            "anyOf": [
              {
                "type": "string",
                "description": "own: each side's EUR only, the default.",
                "enum": [
                  "own"
                ]
              },
              {
                "type": "object",
                "description": "A common horizon: cumulative rows at that many years.",
                "required": [
                  "years"
                ],
                "properties": {
                  "years": {
                    "type": "integer",
                    "description": "Years.",
                    "minimum": 1,
                    "maximum": 50
                  }
                },
                "additionalProperties": false
              }
            ],
            "description": "Each side's cumulative at a common horizon beside its EUR; needs EUR on both sides (a 400 naming the side without)."
          },
          "align": {
            "type": "string",
            "description": "`calendar` adds curves.calendar, each side's curve by calendar month (needs include curves and a well with a TIL date on each side, or a start date on every well of a forecast source side); months_on, the default, adds nothing.",
            "enum": [
              "months_on",
              "calendar"
            ]
          },
          "deck_id": {
            "type": "string",
            "description": "With include value (a 400 without it): the deck to price both sides with, as POST /economics takes it; left out, the set's default deck.",
            "enum": [
              "prototype-midland-flat",
              "house-70-3",
              "illustrative-haynesville-gas"
            ]
          },
          "deck": {
            "type": "object",
            "description": "With include value (a 400 without it): overrides of the deck's values, each within its range, as POST /economics takes them.",
            "required": [],
            "properties": {
              "oil_price": {
                "type": "number",
                "description": "$/bbl; 75 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 300
              },
              "oil_differential": {
                "type": "number",
                "description": "$/bbl; 4 in the illustrative Midland deck.",
                "minimum": -50,
                "maximum": 50
              },
              "gas_price": {
                "type": "number",
                "description": "$/mcf; 3.5 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 50
              },
              "gas_differential": {
                "type": "number",
                "description": "$/mcf; 1 in the illustrative Midland deck.",
                "minimum": -10,
                "maximum": 10
              },
              "ngl_price": {
                "type": "number",
                "description": "$/bbl; 26 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 200
              },
              "ngl_yield_bbl_per_mmcf": {
                "type": "number",
                "description": "bbl/MMcf; 130 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 300
              },
              "shrink": {
                "type": "number",
                "description": "fraction; 0.8 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 1
              },
              "opex_oil": {
                "type": "number",
                "description": "$/bbl; 5.5 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 100
              },
              "opex_gas": {
                "type": "number",
                "description": "$/mcf; 0.5 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 20
              },
              "opex_water": {
                "type": "number",
                "description": "$/bbl; 0.6 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 20
              },
              "royalty": {
                "type": "number",
                "description": "fraction; 0.25 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 0.5
              },
              "severance_oil": {
                "type": "number",
                "description": "fraction; 0.046 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 0.5
              },
              "severance_gas": {
                "type": "number",
                "description": "fraction; 0.075 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 0.5
              },
              "ad_valorem": {
                "type": "number",
                "description": "fraction; 0.025 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 0.2
              },
              "capex_per_well": {
                "type": "number",
                "description": "$; 2500000 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 50000000
              },
              "capex_drilling_per_ft": {
                "type": "number",
                "description": "$/ft; 150 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 2000
              },
              "capex_stimulation_per_ft": {
                "type": "number",
                "description": "$/ft; 125 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 2000
              },
              "capex_proppant_per_lb": {
                "type": "number",
                "description": "$/lb; 0.08 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 2
              },
              "capex_fluid_per_bbl": {
                "type": "number",
                "description": "$/bbl; 3 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 50
              },
              "discount_rate": {
                "type": "number",
                "description": "fraction per year; 0.25 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 1
              }
            },
            "additionalProperties": false
          },
          "conventions": {
            "type": "string",
            "description": "With include value (a 400 without it): how NPV and payback are counted, as POST /economics takes it.",
            "enum": [
              "prototype",
              "fe"
            ],
            "default": "prototype"
          }
        },
        "additionalProperties": false
      },
      "ComparisonPairing": {
        "type": "object",
        "description": "How to pair the sides' wells; adds pairs to the answer.",
        "required": [],
        "properties": {
          "by": {
            "type": "string",
            "description": "auto (default): name when every well on both sides has a real name and none repeats on a side, else location; with a forecast source side, saved, else name, else uwi.\n\n- name: names found once on each side; a repeated name's wells pair by location within it.\n- location: heel and bottom hole each within tolerance_ft; same formation first, then closest, then nearest TVD; one to one.\n- index: by position, with a warning.\n- map: the pairs in map.\n- uwi and saved: forecast source sides only; location and index: plan sides only.",
            "enum": [
              "auto",
              "name",
              "location",
              "index",
              "map",
              "uwi",
              "saved"
            ],
            "default": "auto"
          },
          "tolerance_ft": {
            "type": "number",
            "description": "With auto or location: how far apart, ft, a pair's heels (else surface holes) and bottom holes may each be; 300 by default. With another by it is a 400.",
            "minimum": 1,
            "maximum": 5280,
            "default": 300
          },
          "map": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": [
                  "integer",
                  "string"
                ],
                "description": "A plan well index, a whole number from 0; on a forecast source side, its Well ID."
              },
              "description": "[a, b].",
              "minItems": 2,
              "maxItems": 2
            },
            "description": "With by map, and only then: the pairs, each well once; an index or Well ID outside its side's wells or used twice is a 400 naming the entry (pair.map[k])."
          }
        },
        "additionalProperties": false
      },
      "ComparisonWellsPage": {
        "type": "object",
        "description": "Paging for the per-well rows; needs include wells (a 400 without).",
        "required": [],
        "properties": {
          "limit": {
            "type": "integer",
            "description": "Rows a page: 1 to 1,000, 100 by default.",
            "minimum": 1,
            "maximum": 1000,
            "default": 100
          },
          "cursor": {
            "type": "string",
            "description": "wells.next_cursor from the previous page, with the same request otherwise."
          },
          "sort": {
            "type": "string",
            "description": "abs_delta (default): the size of delta; delta: delta itself; a_index: side a's well index (a forecast source side a: its file order). Rows without the value go last; ties in side a's order.",
            "enum": [
              "abs_delta",
              "delta",
              "a_index"
            ],
            "default": "abs_delta"
          },
          "order": {
            "type": "string",
            "description": "desc by default for abs_delta and delta, asc for a_index.",
            "enum": [
              "asc",
              "desc"
            ]
          }
        },
        "additionalProperties": false
      },
      "ComparisonSideEcho": {
        "type": "object",
        "description": "What one side is and what made it.",
        "required": [
          "kind",
          "plan",
          "scenario",
          "design",
          "model_set",
          "release",
          "run_at",
          "decline",
          "bands",
          "wells",
          "wells_with_forecast",
          "unplaced"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "description": "What the side is: plan. A forecast source side's echo is a SourceSideEcho, whose kind is source.",
            "enum": [
              "plan",
              "source"
            ]
          },
          "plan": {
            "type": "object",
            "description": "The plan.",
            "required": [
              "id",
              "name"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Plan id.",
                "format": "uuid"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Plan name."
              }
            },
            "additionalProperties": false
          },
          "scenario": {
            "type": [
              "string",
              "null"
            ],
            "description": "The scenario compared; null for a plan without scenarios."
          },
          "design": {
            "type": "object",
            "description": "The design compared.",
            "required": [
              "index",
              "name"
            ],
            "properties": {
              "index": {
                "type": "integer",
                "description": "The design, as its index in `designs`.",
                "minimum": 0
              },
              "name": {
                "type": "string",
                "description": "The design's name."
              }
            },
            "additionalProperties": false
          },
          "model_set": {
            "type": "string",
            "description": "The model set that ran the plan: a stored plan's record names it; a plan kept in this server's memory is on the set the request reached."
          },
          "release": {
            "type": "string",
            "description": "The app version that ran the plan, as GET /health `app_version`: a stored plan's record names it; a plan kept in memory ran on this server's; unknown when the server has no VERSION."
          },
          "run_at": {
            "type": "string",
            "description": "When the plan was created, UTC.",
            "format": "date-time"
          },
          "decline": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Decline"
              },
              {
                "type": "null"
              }
            ],
            "description": "The EUR settings the plan was fit with, as GET /plans/{id} `decline` (per_well when one of the side's wells has its own); null without EUR."
          },
          "bands": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BandsEcho"
              },
              {
                "type": "null"
              }
            ],
            "description": "The plan's bands, as GET /plans/{id} `bands`; null when it was made without them."
          },
          "wells": {
            "type": "integer",
            "description": "The side's wells: the scenario's, else the plan's.",
            "minimum": 0
          },
          "wells_with_forecast": {
            "type": "integer",
            "description": "Of them, wells with a forecast under the design, as the matching GET /plans/{id} `totals` row counts them.",
            "minimum": 0
          },
          "unplaced": {
            "type": "object",
            "description": "Wells the plan couldn't place.",
            "required": [
              "count",
              "message"
            ],
            "properties": {
              "count": {
                "type": "integer",
                "description": "The side's wells that couldn't be placed (per_well_errors).",
                "minimum": 0
              },
              "message": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The first one's reason; null when none."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "SourceSideEcho": {
        "type": "object",
        "description": "What a forecast source side is and how its numbers were made.",
        "required": [
          "kind",
          "source",
          "format",
          "file",
          "conventions",
          "units",
          "gas_basis",
          "reserves_category",
          "wells",
          "wells_with_forecast",
          "curves"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "description": "A forecast source side.",
            "enum": [
              "source"
            ]
          },
          "source": {
            "type": "object",
            "description": "The forecast source.",
            "required": [
              "id",
              "name"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Forecast source id.",
                "format": "uuid"
              },
              "name": {
                "type": "string",
                "description": "Its name."
              }
            },
            "additionalProperties": false
          },
          "format": {
            "type": "string",
            "description": "The file's format, as GET /forecast-sources/{id} `format`."
          },
          "file": {
            "type": "object",
            "description": "The file the source was read from.",
            "required": [
              "name",
              "bytes",
              "read_at"
            ],
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The file's name; null when none was sent."
              },
              "bytes": {
                "type": "integer",
                "description": "Its size.",
                "minimum": 0
              },
              "read_at": {
                "type": "string",
                "description": "When it was read and saved, UTC.",
                "format": "date-time"
              }
            },
            "additionalProperties": false
          },
          "conventions": {
            "type": "object",
            "description": "The profile's conventions, as GET /conventions?include=decline_profiles lists them.",
            "required": [
              "profile",
              "declines",
              "year_days",
              "months"
            ],
            "properties": {
              "profile": {
                "type": "string",
                "description": "The decline profile its curves ran under.",
                "enum": [
                  "valnav",
                  "mosaic",
                  "combocurve",
                  "novi",
                  "aries"
                ]
              },
              "declines": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A decline basis.",
                  "enum": [
                    "nominal",
                    "secant",
                    "tangent"
                  ]
                },
                "description": "The decline bases the profile reads."
              },
              "year_days": {
                "type": "number",
                "description": "Days in the profile's year."
              },
              "months": {
                "type": "string",
                "description": "calendar, or 30-day months from ip day 0.",
                "enum": [
                  "calendar",
                  "30-day"
                ]
              }
            },
            "additionalProperties": false
          },
          "units": {
            "type": "string",
            "description": "The units the file was in; every number here is converted to bbl, mcf and BOE.",
            "enum": [
              "imperial",
              "metric"
            ]
          },
          "gas_basis": {
            "type": "string",
            "description": "raw or sales gas, as the source states it; Novi forecasts raw gas.",
            "enum": [
              "raw",
              "sales"
            ]
          },
          "reserves_category": {
            "type": "string",
            "description": "The reserves category compared."
          },
          "wells": {
            "type": "integer",
            "description": "The source's wells under the category.",
            "minimum": 0
          },
          "wells_with_forecast": {
            "type": "integer",
            "description": "Of them, wells with a stream Novi's Arps decline calculation could run.",
            "minimum": 0
          },
          "curves": {
            "type": "integer",
            "description": "The source's curves under the category.",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "ComparisonTotal": {
        "type": "object",
        "description": "One total on both sides.",
        "required": [
          "metric",
          "unit",
          "ip_day",
          "a",
          "b",
          "delta",
          "delta_pct",
          "a_wells",
          "b_wells"
        ],
        "properties": {
          "metric": {
            "type": "string",
            "description": "What the row totals.\n\n- eur_<stream>: EUR summed over the side's wells with that EUR (BOE over those with both oil and gas).\n- cum_<stream>: the summed forecast's cumulative at ip_day (BOE: the `forecast.boe` total GET /plans/{id}?boe=true serves, over the wells with both oil and gas forecasts); on a horizon row (`horizon_years` set), at that horizon's day (BOE over those with both).",
            "enum": [
              "eur_oil",
              "eur_gas",
              "eur_water",
              "eur_boe",
              "cum_oil",
              "cum_gas",
              "cum_boe"
            ]
          },
          "unit": {
            "type": "string",
            "description": "The unit of a, b and delta: bbl (oil, water), mcf (gas) or BOE.",
            "enum": [
              "bbl",
              "mcf",
              "BOE"
            ]
          },
          "ip_day": {
            "type": [
              "integer",
              "null"
            ],
            "description": "For a cum_ row, the ip_day; null for an EUR row."
          },
          "a": {
            "type": [
              "number",
              "null"
            ],
            "description": "Side a's total; null when no well has it."
          },
          "b": {
            "type": [
              "number",
              "null"
            ],
            "description": "Side b's total; null when no well has it."
          },
          "delta": {
            "type": [
              "number",
              "null"
            ],
            "description": "b − a, rounded to 0.1; null when either is null."
          },
          "delta_pct": {
            "type": [
              "number",
              "null"
            ],
            "description": "(b − a) / a × 100, relative to side a, rounded to 0.01; null when a is 0 or either is null."
          },
          "a_wells": {
            "type": "integer",
            "description": "Side a's wells the total covers.",
            "minimum": 0
          },
          "b_wells": {
            "type": "integer",
            "description": "Side b's wells the total covers.",
            "minimum": 0
          },
          "horizon_years": {
            "type": "integer",
            "description": "On a horizon row only: the years asked; ip_day is that horizon's day.",
            "minimum": 1
          }
        },
        "additionalProperties": false
      },
      "ComparisonSpread": {
        "type": "object",
        "description": "One side's distribution of the metric over its wells, as GET /plans/{id}/stats gives it, in distribution.unit.",
        "required": [
          "wells",
          "missing",
          "min",
          "max",
          "mean",
          "quantiles"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "In a pad group, this side's name for the pad when its plan gives one in `pads[].name`; absent otherwise. The sides are paired by `key` and may name it differently."
          },
          "wells": {
            "type": "integer",
            "description": "Wells with a value; every figure describes them.",
            "minimum": 0
          },
          "missing": {
            "type": "integer",
            "description": "Wells without one: no forecast, a failed EUR fit, or BOE without both oil and gas.",
            "minimum": 0
          },
          "min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Smallest value; null when no well has one."
          },
          "max": {
            "type": [
              "number",
              "null"
            ],
            "description": "Largest value; null when no well has one."
          },
          "mean": {
            "type": [
              "number",
              "null"
            ],
            "description": "Mean value per well; null when no well has one."
          },
          "quantiles": {
            "type": "object",
            "description": "q10, q50 and q90 of the wells' values (linear interpolation between the closest ranks), not P-level bands; each null when no well has a value.",
            "patternProperties": {
              "^q([1-9]|[1-9][0-9])$": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "additionalProperties": false
          },
          "others": {
            "type": "integer",
            "description": "On a group's Other row only: how many of the side's groups it sums.",
            "minimum": 1
          }
        },
        "additionalProperties": false
      },
      "ComparisonDelta": {
        "type": "object",
        "description": "b − a (rounded to 0.1), or (b − a) / a × 100 relative to side a (rounded to 0.01) as delta_pct.",
        "required": [
          "mean",
          "q50"
        ],
        "properties": {
          "mean": {
            "type": [
              "number",
              "null"
            ],
            "description": "Of the mean per well; null when either side has none."
          },
          "q50": {
            "type": [
              "number",
              "null"
            ],
            "description": "Of the median well; null when either side has none."
          }
        },
        "additionalProperties": false
      },
      "ComparisonGroup": {
        "type": "object",
        "description": "One group on both sides.",
        "required": [
          "key",
          "a",
          "b",
          "delta",
          "delta_pct"
        ],
        "properties": {
          "key": {
            "type": [
              "string",
              "integer",
              "null"
            ],
            "description": "The design index, the formation (null for wells without one), the scenario, the pad key (null for wells without one), or Other on the summed row. Pads never fold into Other."
          },
          "a": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ComparisonSpread"
              },
              {
                "type": "null"
              }
            ],
            "description": "Side a's wells in the group; null when it has none."
          },
          "b": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ComparisonSpread"
              },
              {
                "type": "null"
              }
            ],
            "description": "Side b's wells in the group; null when it has none."
          },
          "delta": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ComparisonDelta"
              },
              {
                "type": "null"
              }
            ],
            "description": "b − a; null when a side has no wells in the group."
          },
          "delta_pct": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ComparisonDelta"
              },
              {
                "type": "null"
              }
            ],
            "description": "Relative to side a; null when a side has no wells in the group."
          }
        },
        "additionalProperties": false
      },
      "ComparisonCurve": {
        "type": "object",
        "description": "One side's summed curve.",
        "required": [
          "ip_days",
          "cum",
          "rate"
        ],
        "properties": {
          "ip_days": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "Days since TIL.",
              "minimum": 1
            },
            "description": "The forecast's days."
          },
          "cum": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "Cumulative volume, in curves.unit."
            },
            "description": "The side's summed cumulative, as GET /plans/{id} `totals` `forecast` (BOE: its `forecast.boe` with boe=true, over the wells with both oil and gas forecasts)."
          },
          "rate": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "Average daily rate over the step ending that day, in curves.rate_unit, to 0.01."
            },
            "description": "Each step's rate: the cumulative's rise from the day before (from 0 on day 0) over the days between."
          },
          "bands": {
            "type": "object",
            "description": "With include bands, where the side's plan was made with bands and every well has them; a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan.",
            "required": [
              "p10",
              "p90"
            ],
            "properties": {
              "p10": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Cumulative."
                },
                "description": "The summed P10 cumulative (Novi's P10 is the low curve)."
              },
              "p90": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Cumulative."
                },
                "description": "The summed P90 cumulative."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "ComparisonCurves": {
        "type": "object",
        "description": "Each side's summed curve for the metric's stream, with include curves.",
        "required": [
          "axis",
          "stream",
          "unit",
          "rate_unit",
          "a",
          "b"
        ],
        "properties": {
          "axis": {
            "type": "string",
            "description": "Curves run by days since TIL (ip_days), not calendar dates.",
            "enum": [
              "ip_days"
            ]
          },
          "stream": {
            "type": "string",
            "description": "The metric's stream.",
            "enum": [
              "oil",
              "gas",
              "boe"
            ]
          },
          "unit": {
            "type": "string",
            "description": "The cumulative's unit.",
            "enum": [
              "bbl",
              "mcf",
              "BOE"
            ]
          },
          "rate_unit": {
            "type": "string",
            "description": "The rate's unit: the volume per day.",
            "enum": [
              "bbl/d",
              "mcf/d",
              "BOE/d"
            ]
          },
          "a": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ComparisonCurve"
              },
              {
                "type": "null"
              }
            ],
            "description": "Side a's; null when none of its wells has the stream (BOE: both oil and gas)."
          },
          "b": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ComparisonCurve"
              },
              {
                "type": "null"
              }
            ],
            "description": "Side b's; null when none of its wells has the stream (BOE: both oil and gas)."
          },
          "calendar": {
            "type": "object",
            "description": "With align calendar: each side's summed curve by calendar month.",
            "required": [
              "a",
              "b"
            ],
            "properties": {
              "a": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/ComparisonDateCurve"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Side a's; null when none of its wells has the stream (BOE: both oil and gas)."
              },
              "b": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/ComparisonDateCurve"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Side b's; null when none of its wells has the stream (BOE: both oil and gas)."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "ComparisonDateCurve": {
        "type": "object",
        "description": "One side's summed curve by calendar month.",
        "required": [
          "dates",
          "cum",
          "rate"
        ],
        "properties": {
          "dates": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A month start, YYYY-MM-DD.",
              "format": "date"
            },
            "description": "Each month start from the side's first TIL month, as GET /plans/{id} totals.by_date.dates."
          },
          "cum": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "Cumulative volume at that date, in curves.unit."
            },
            "description": "The side's cumulative, as totals.by_date; BOE over the wells with both oil and gas, as GET /plans/{id}?boe=true totals count them (each well's oil plus gas / 6, summed, to 0.1)."
          },
          "rate": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "Average daily rate since the month before, in curves.rate_unit, to 0.01."
            },
            "description": "Each month's rate: the cumulative's rise over the calendar days between month starts; null for the first."
          },
          "bands": {
            "type": "object",
            "description": "With include bands, where every well of the side has bands; a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan.",
            "required": [
              "p10",
              "p90"
            ],
            "properties": {
              "p10": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Cumulative."
                },
                "description": "The summed P10 (Novi's P10 is the low curve)."
              },
              "p90": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Cumulative."
                },
                "description": "The summed P90."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "ComparisonWarning": {
        "type": "object",
        "description": "A reason a difference may not be the plans'.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable code; more may come.\n\n- Any sides: different_model_sets, models_changed, different_releases, different_eur_settings, side_without_eur, wells_without_forecast, side_without_bands, index_pairing, duplicate_names, no_band_position.\n- With a forecast source side: gas_basis_differs, conventions_differ, horizons_differ, source_unpaired, and with include value, value_wells_differ."
          },
          "message": {
            "type": "string",
            "description": "One sentence to show beside the numbers."
          }
        },
        "additionalProperties": false
      },
      "Comparison": {
        "type": "object",
        "description": "Two sides compared.",
        "required": [
          "a",
          "b",
          "totals",
          "distribution",
          "warnings"
        ],
        "properties": {
          "a": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ComparisonSideEcho"
              },
              {
                "$ref": "#/components/schemas/SourceSideEcho"
              }
            ],
            "description": "Side a's echo: a plan side's, or a forecast source side's."
          },
          "b": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ComparisonSideEcho"
              },
              {
                "$ref": "#/components/schemas/SourceSideEcho"
              }
            ],
            "description": "Side b's echo: a plan side's, or a forecast source side's."
          },
          "totals": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComparisonTotal"
            },
            "description": "EUR rows when both sides have EUR, then with horizon the cumulative rows at its day (`horizon_years` set), then cumulative rows at ip_day for a cum_ metric. A forecast source side's EUR runs each curve to its own limit or end date."
          },
          "distribution": {
            "type": "object",
            "description": "Each side's distribution of the metric over its wells, and how it moved.",
            "required": [
              "metric",
              "unit",
              "ip_day",
              "a",
              "b",
              "delta",
              "delta_pct"
            ],
            "properties": {
              "metric": {
                "type": "string",
                "description": "The metric measured.",
                "enum": [
                  "eur_boe",
                  "eur_oil",
                  "eur_gas",
                  "cum_boe",
                  "cum_oil",
                  "cum_gas"
                ]
              },
              "unit": {
                "type": "string",
                "description": "The unit of every value: bbl (oil), mcf (gas) or BOE.",
                "enum": [
                  "bbl",
                  "mcf",
                  "BOE"
                ]
              },
              "ip_day": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "For a cum_ metric, the ip_day measured; null for an eur_ metric."
              },
              "normalize_lateral_ft": {
                "type": "number",
                "description": "With normalize_lateral_ft: the lateral every value was scaled to, ft."
              },
              "a": {
                "$ref": "#/components/schemas/ComparisonSpread"
              },
              "b": {
                "$ref": "#/components/schemas/ComparisonSpread"
              },
              "delta": {
                "$ref": "#/components/schemas/ComparisonDelta"
              },
              "delta_pct": {
                "$ref": "#/components/schemas/ComparisonDelta"
              }
            },
            "additionalProperties": false
          },
          "group_by": {
            "type": "string",
            "description": "With group_by: what groups is by.",
            "enum": [
              "design",
              "formation",
              "scenario",
              "pad"
            ]
          },
          "groups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComparisonGroup"
            },
            "description": "With group_by: one row per key on either side, in GET /plans/{id}/stats order (scenarios: side a's plan's order, then any only side b's plan has); pad keys use side a plan order then new side b keys, null last, with no cap or Other row. For other groupings, at most 50, the rest in one Other row."
          },
          "curves": {
            "$ref": "#/components/schemas/ComparisonCurves"
          },
          "pairs": {
            "$ref": "#/components/schemas/ComparisonPairs"
          },
          "wells": {
            "$ref": "#/components/schemas/ComparisonWells"
          },
          "inputs": {
            "$ref": "#/components/schemas/ComparisonInputs"
          },
          "value": {
            "$ref": "#/components/schemas/ComparisonValue"
          },
          "warnings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComparisonWarning"
            },
            "description": "Reasons a difference may not come from the plans, in a fixed order; empty when there are none."
          }
        },
        "additionalProperties": false
      },
      "ComparisonValue": {
        "type": "object",
        "description": "With include value: each side priced as one POST /economics scenario under one deck and conventions, and the difference.",
        "required": [
          "label",
          "deck",
          "conventions",
          "a",
          "b",
          "delta"
        ],
        "properties": {
          "label": {
            "type": "string",
            "description": "What to show beside the numbers: Simulated half-cycle economics, deck <name>."
          },
          "deck": {
            "type": "object",
            "description": "The effective deck.",
            "required": [
              "deck_id",
              "version",
              "name",
              "overrides",
              "discount_rate",
              "values"
            ],
            "properties": {
              "deck_id": {
                "type": "string",
                "description": "The deck's id."
              },
              "version": {
                "type": "integer",
                "description": "Its version.",
                "minimum": 1
              },
              "name": {
                "type": "string",
                "description": "Its display name, as GET /economics/decks lists it; name results by it."
              },
              "overrides": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A field.",
                  "enum": [
                    "oil_price",
                    "oil_differential",
                    "gas_price",
                    "gas_differential",
                    "ngl_price",
                    "ngl_yield_bbl_per_mmcf",
                    "shrink",
                    "opex_oil",
                    "opex_gas",
                    "opex_water",
                    "royalty",
                    "severance_oil",
                    "severance_gas",
                    "ad_valorem",
                    "capex_per_well",
                    "capex_drilling_per_ft",
                    "capex_stimulation_per_ft",
                    "capex_proppant_per_lb",
                    "capex_fluid_per_bbl",
                    "discount_rate"
                  ]
                },
                "description": "The fields this request overrode."
              },
              "discount_rate": {
                "type": "number",
                "description": "The effective annual discount rate used for npv."
              },
              "values": {
                "type": "object",
                "description": "The values priced with.",
                "required": [
                  "oil_price",
                  "oil_differential",
                  "gas_price",
                  "gas_differential",
                  "ngl_price",
                  "ngl_yield_bbl_per_mmcf",
                  "shrink",
                  "opex_oil",
                  "opex_gas",
                  "opex_water",
                  "royalty",
                  "severance_oil",
                  "severance_gas",
                  "ad_valorem",
                  "capex_per_well",
                  "capex_drilling_per_ft",
                  "capex_stimulation_per_ft",
                  "capex_proppant_per_lb",
                  "capex_fluid_per_bbl",
                  "discount_rate"
                ],
                "properties": {
                  "oil_price": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "oil_differential": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "gas_price": {
                    "type": "number",
                    "description": "$/mcf"
                  },
                  "gas_differential": {
                    "type": "number",
                    "description": "$/mcf"
                  },
                  "ngl_price": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "ngl_yield_bbl_per_mmcf": {
                    "type": "number",
                    "description": "bbl/MMcf"
                  },
                  "shrink": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "opex_oil": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "opex_gas": {
                    "type": "number",
                    "description": "$/mcf"
                  },
                  "opex_water": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "royalty": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "severance_oil": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "severance_gas": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "ad_valorem": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "capex_per_well": {
                    "type": "number",
                    "description": "$"
                  },
                  "capex_drilling_per_ft": {
                    "type": "number",
                    "description": "$/ft"
                  },
                  "capex_stimulation_per_ft": {
                    "type": "number",
                    "description": "$/ft"
                  },
                  "capex_proppant_per_lb": {
                    "type": "number",
                    "description": "$/lb"
                  },
                  "capex_fluid_per_bbl": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "discount_rate": {
                    "type": "number",
                    "description": "fraction per year"
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "conventions": {
            "type": "string",
            "description": "The conventions priced under.",
            "enum": [
              "prototype",
              "fe"
            ]
          },
          "a": {
            "$ref": "#/components/schemas/ComparisonValueSide"
          },
          "b": {
            "$ref": "#/components/schemas/ComparisonValueSide"
          },
          "delta": {
            "type": "object",
            "description": "b − a, rounded half away from 0 to 0.01: swapping the sides negates every value, and a side against itself gives 0.",
            "required": [
              "capex",
              "npv",
              "irr_pct",
              "payback_months",
              "breakeven"
            ],
            "properties": {
              "capex": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "b − a, $, to 0.01; null when a side has no economics."
              },
              "npv": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "b − a, $, to 0.01; null when a side has no economics."
              },
              "irr_pct": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "b − a, percentage points, to 0.01; null when a side has no economics or no IRR."
              },
              "payback_months": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "b − a, months, to 0.01; null when a side has no economics or never pays back."
              },
              "breakeven": {
                "type": "object",
                "description": "b − a of each breakeven price.",
                "required": [
                  "oil_price",
                  "gas_price"
                ],
                "properties": {
                  "oil_price": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "b − a, $/bbl, to 0.01; null when a side has no breakeven oil price."
                  },
                  "gas_price": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "b − a, $/mcf, to 0.01; null when a side has no breakeven gas price."
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "ComparisonValueSide": {
        "type": "object",
        "description": "One side priced.",
        "required": [
          "economics",
          "reason",
          "breakeven",
          "wells",
          "priced",
          "unpriced"
        ],
        "properties": {
          "economics": {
            "type": [
              "object",
              "null"
            ],
            "description": "The side's economics, as POST /economics gives a scenario's, or null.",
            "required": [
              "capex",
              "irr_pct",
              "payback_months",
              "npv"
            ],
            "properties": {
              "capex": {
                "type": "number",
                "description": "Capex, $, all at month 0."
              },
              "irr_pct": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "IRR, % a year, annualized from the monthly rate (capped at 100% a month); null when the flows never return their capex."
              },
              "payback_months": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Months until the running total turns non-negative: interpolated within the month, or whole months under fe; null when it never does."
              },
              "npv": {
                "type": "number",
                "description": "NPV, $, at the effective deck discount_rate, discounted as conventions says."
              }
            },
            "additionalProperties": false
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why economics is null: the first well without a cash flow and why, as POST /economics names it, or that none of a forecast source side's wells paired."
          },
          "breakeven": {
            "type": [
              "object",
              "null"
            ],
            "description": "As POST /economics include breakeven gives a scenario's: the flat oil and gas prices at which the side's npv is 0, every other deck value and override held; null when economics is null.",
            "required": [
              "oil_price",
              "gas_price",
              "discount_rate"
            ],
            "properties": {
              "oil_price": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "WTI, $/bbl: the flat oil price at which npv is 0, to within $0.000001; null when npv doesn't cross 0 between oil_price's min and max (GET /economics/deck)."
              },
              "gas_price": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Henry Hub, $/mcf: the flat gas price at which npv is 0, to within $0.000001; null when npv doesn't cross 0 between gas_price's min and max."
              },
              "discount_rate": {
                "type": "number",
                "description": "The effective annual discount rate npv was taken at, as deck.discount_rate."
              }
            },
            "additionalProperties": false
          },
          "wells": {
            "type": "integer",
            "description": "The side's wells: a plan side's, or every well of a forecast source side under its reserves category.",
            "minimum": 1
          },
          "priced": {
            "type": "integer",
            "description": "Wells with a cash flow.",
            "minimum": 0
          },
          "unpriced": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A forecast source well left out.",
              "required": [
                "well_id",
                "reason"
              ],
              "properties": {
                "well_id": {
                  "type": "string",
                  "description": "The forecast source's Well ID."
                },
                "reason": {
                  "type": "string",
                  "description": "Why it isn't priced."
                }
              },
              "additionalProperties": false
            },
            "description": "On a forecast source side, each well that didn't pair with a plan well, in the source's order; empty on a plan side."
          }
        },
        "additionalProperties": false
      },
      "ComparisonPairs": {
        "type": "object",
        "description": "With pair, include wells or include inputs: how the wells paired.",
        "required": [
          "by",
          "paired",
          "a_only",
          "b_only"
        ],
        "properties": {
          "by": {
            "type": "string",
            "description": "The method that paired them: what pair.by asked, or for auto, name or location.",
            "enum": [
              "name",
              "location",
              "index",
              "map",
              "uwi",
              "saved"
            ]
          },
          "paired": {
            "type": "integer",
            "description": "Pairs.",
            "minimum": 0
          },
          "a_only": {
            "type": "array",
            "items": {
              "type": [
                "integer",
                "string"
              ],
              "description": "A plan well index; on a forecast source side, a Well ID."
            },
            "description": "Side a's wells left unpaired, ascending; a forecast source side's in its file order."
          },
          "b_only": {
            "type": "array",
            "items": {
              "type": [
                "integer",
                "string"
              ],
              "description": "A plan well index; on a forecast source side, a Well ID."
            },
            "description": "Side b's wells left unpaired, ascending; a forecast source side's in its file order."
          },
          "tolerance_ft": {
            "type": "number",
            "description": "By location only: the tolerance used, ft."
          }
        },
        "additionalProperties": false
      },
      "ComparisonWellRow": {
        "type": "object",
        "description": "One paired well: a_index or a_well_id, and b_index or b_well_id.",
        "required": [
          "label",
          "a",
          "b",
          "delta",
          "delta_pct"
        ],
        "properties": {
          "a_index": {
            "type": "integer",
            "description": "Side a's plan well index; a forecast source side a has a_well_id instead.",
            "minimum": 0
          },
          "b_index": {
            "type": "integer",
            "description": "Side b's plan well index; a forecast source side b has b_well_id instead.",
            "minimum": 0
          },
          "a_well_id": {
            "type": "string",
            "description": "Side a's Well ID when side a is a forecast source."
          },
          "b_well_id": {
            "type": "string",
            "description": "Side b's Well ID when side b is a forecast source."
          },
          "label": {
            "type": "string",
            "description": "Side a's well name, else Plan well N; a forecast source side a's Well ID."
          },
          "b_label": {
            "type": "string",
            "description": "When side b is a plan: its well's name, else Plan well N, as label names side a's; a forecast source side b has b_well_id instead."
          },
          "a": {
            "type": [
              "number",
              "null"
            ],
            "description": "Side a's value of the metric, as distribution measures it, to 0.1; null without one."
          },
          "b": {
            "type": [
              "number",
              "null"
            ],
            "description": "Side b's value, likewise."
          },
          "delta": {
            "type": [
              "number",
              "null"
            ],
            "description": "b − a, rounded to 0.1; null when either is null."
          },
          "delta_pct": {
            "type": [
              "number",
              "null"
            ],
            "description": "(b − a) / a × 100, relative to side a, rounded to 0.01; null when a is 0 or either is null."
          },
          "band_position": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "below_p10",
              "p10_p90",
              "above_p90",
              null
            ],
            "description": "With band_eur on side a and an eur_ metric: where b falls in side a's P10 to P90 EUR (below_p10, p10_p90 with the edges inside, above_p90); null when b or the band is missing."
          }
        },
        "additionalProperties": false
      },
      "ComparisonWellSummary": {
        "type": "object",
        "description": "Over every pair, so the same on every page.",
        "required": [
          "paired",
          "metric",
          "unit",
          "delta_pct",
          "left_out"
        ],
        "properties": {
          "paired": {
            "type": "integer",
            "description": "Pairs.",
            "minimum": 0
          },
          "metric": {
            "type": "string",
            "description": "The metric measured.",
            "enum": [
              "eur_boe",
              "eur_oil",
              "eur_gas",
              "cum_boe",
              "cum_oil",
              "cum_gas"
            ]
          },
          "unit": {
            "type": "string",
            "description": "The unit of a, b and delta: bbl, mcf or BOE.",
            "enum": [
              "bbl",
              "mcf",
              "BOE"
            ]
          },
          "delta_pct": {
            "type": "object",
            "description": "Each pair's percent change, relative to side a.",
            "required": [
              "q10",
              "q50",
              "q90"
            ],
            "properties": {
              "values": {
                "type": "array",
                "items": {
                  "type": "number",
                  "description": "A pair's delta_pct."
                },
                "description": "Under 20 pairs: every delta_pct, ascending."
              },
              "histogram": {
                "type": "object",
                "description": "At 20 pairs or more.",
                "required": [
                  "edges",
                  "counts"
                ],
                "properties": {
                  "edges": {
                    "type": "array",
                    "items": {
                      "type": "number",
                      "description": "A bin edge, %, to 0.01."
                    },
                    "description": "Equal-width bins from the smallest to the largest delta_pct; ceil(log2 n) + 1 bins (Sturges, n the pairs with a delta_pct), one when all are equal, none when no pair has one."
                  },
                  "counts": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "description": "Pairs in the bin.",
                      "minimum": 0
                    },
                    "description": "They add up to the pairs with a delta_pct; the last bin is closed."
                  }
                },
                "additionalProperties": false
              },
              "q10": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Of the pairs' delta_pct (linear between closest ranks), to 0.01; quantiles of pairs, not P-levels."
              },
              "q50": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The median pair's."
              },
              "q90": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Of the pairs' delta_pct."
              }
            },
            "additionalProperties": false
          },
          "left_out": {
            "type": "integer",
            "description": "Pairs with no delta_pct: side a's value 0, or either value missing.",
            "minimum": 0
          },
          "band": {
            "type": "object",
            "description": "With band_eur on side a and an eur_ metric: the four add up to paired.",
            "required": [
              "below_p10",
              "p10_p90",
              "above_p90",
              "none"
            ],
            "properties": {
              "below_p10": {
                "type": "integer",
                "description": "Pairs whose b is below side a's P10.",
                "minimum": 0
              },
              "p10_p90": {
                "type": "integer",
                "description": "Inside, edges included.",
                "minimum": 0
              },
              "above_p90": {
                "type": "integer",
                "description": "Above side a's P90.",
                "minimum": 0
              },
              "none": {
                "type": "integer",
                "description": "Without a position: b or the band missing.",
                "minimum": 0
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "ComparisonWells": {
        "type": "object",
        "description": "With include wells.",
        "required": [
          "summary",
          "rows",
          "next_cursor"
        ],
        "properties": {
          "summary": {
            "$ref": "#/components/schemas/ComparisonWellSummary"
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComparisonWellRow"
            },
            "description": "This page of the pairs, in wells.sort order."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Send as wells.cursor for the next page; null on the last."
          }
        },
        "additionalProperties": false
      },
      "ComparisonInputChange": {
        "type": "object",
        "description": "One input that differs between paired wells.",
        "required": [
          "field",
          "unit",
          "wells",
          "typical_change"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "The input: formation, tvd_ft (as landed), lateral_length_ft, fluid_bbl_per_ft, proppant_lb_per_ft (as run under each side's design), til_date, or with EUR on both sides decline.eur_years and decline.<stream>.terminal_decline, b_min or b_max."
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "The unit of typical_change: ft, bbl/ft, lb/ft, days, years or fraction per year; null for formation and the b exponents."
          },
          "wells": {
            "type": "integer",
            "description": "Pairs where it differs, at the precision it is shown to.",
            "minimum": 1
          },
          "typical_change": {
            "anyOf": [
              {
                "type": "number",
                "description": "b − a: the median among the pairs that differ with both values."
              },
              {
                "type": "object",
                "description": "For formation: the most common change.",
                "required": [
                  "from",
                  "to"
                ],
                "properties": {
                  "from": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Side a's."
                  },
                  "to": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Side b's."
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "null when no differing pair has both values."
          }
        },
        "additionalProperties": false
      },
      "ComparisonInputs": {
        "type": "object",
        "description": "With include inputs.",
        "required": [
          "changed"
        ],
        "properties": {
          "changed": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComparisonInputChange"
            },
            "description": "Only inputs that differ on at least one pair, in a fixed order; empty when none do."
          }
        },
        "additionalProperties": false
      },
      "ConventionSection": {
        "type": "object",
        "description": "One section of the conventions.",
        "required": [
          "id",
          "title",
          "markdown"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable id, as units."
          },
          "title": {
            "type": "string",
            "description": "Heading."
          },
          "markdown": {
            "type": "string",
            "description": "The section, in Markdown."
          }
        },
        "additionalProperties": false
      },
      "Me": {
        "type": "object",
        "description": "Who the request is.",
        "required": [
          "tenant",
          "user",
          "role"
        ],
        "properties": {
          "tenant": {
            "type": "string",
            "description": "The tenant plans, exports, shares and saved documents belong to."
          },
          "user": {
            "type": "object",
            "description": "The user.",
            "required": [
              "id",
              "email"
            ],
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "User id."
              },
              "email": {
                "type": "string",
                "description": "Email."
              }
            },
            "additionalProperties": false
          },
          "role": {
            "type": "string",
            "description": "staff for Novi, customer for anyone else.",
            "enum": [
              "staff",
              "customer"
            ]
          }
        },
        "additionalProperties": false
      },
      "Conventions": {
        "type": "object",
        "description": "Units and conventions.",
        "required": [
          "api_version",
          "units",
          "boe",
          "p_levels",
          "sections"
        ],
        "properties": {
          "api_version": {
            "type": "string",
            "description": "API version."
          },
          "units": {
            "type": "object",
            "description": "The unit of each quantity in responses; rates are these per day.",
            "required": [
              "oil",
              "gas",
              "water",
              "boe",
              "lateral_length",
              "tvd",
              "proppant",
              "fluid",
              "money"
            ],
            "properties": {
              "oil": {
                "type": "string",
                "description": "Oil volumes."
              },
              "gas": {
                "type": "string",
                "description": "Gas volumes."
              },
              "water": {
                "type": "string",
                "description": "Water volumes."
              },
              "boe": {
                "type": "string",
                "description": "Barrels of oil equivalent."
              },
              "lateral_length": {
                "type": "string",
                "description": "Lateral length."
              },
              "tvd": {
                "type": "string",
                "description": "True vertical depth."
              },
              "proppant": {
                "type": "string",
                "description": "Proppant per lateral foot."
              },
              "fluid": {
                "type": "string",
                "description": "Fluid per lateral foot."
              },
              "money": {
                "type": "string",
                "description": "Money, in economics."
              }
            },
            "additionalProperties": {
              "type": "string"
            }
          },
          "boe": {
            "type": "object",
            "description": "Barrels of oil equivalent.",
            "required": [
              "gas_mcf_per_bbl",
              "label"
            ],
            "properties": {
              "gas_mcf_per_bbl": {
                "type": "number",
                "description": "mcf of gas counted as one barrel of oil: BOE = oil bbl + gas mcf / this."
              },
              "label": {
                "type": "string",
                "description": "How to label BOE, as BOE (6:1)."
              }
            },
            "additionalProperties": false
          },
          "p_levels": {
            "type": "object",
            "description": "P-level names: Novi's P10 is the low curve and P90 the high one, the reverse of SPE PRMS.",
            "required": [
              "low",
              "high",
              "convention"
            ],
            "properties": {
              "low": {
                "const": "P10",
                "description": "The low curve's name."
              },
              "high": {
                "const": "P90",
                "description": "The high curve's name."
              },
              "convention": {
                "type": "string",
                "description": "The convention in one sentence, as exports write it."
              }
            },
            "additionalProperties": false
          },
          "sections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConventionSection"
            },
            "description": "The conventions in prose, in reading order."
          },
          "decline_profiles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeclineProfile"
            },
            "description": "With include=decline_profiles: how each tool turns decline segments into rates and volumes, in this order: valnav, mosaic, combocurve, novi."
          }
        },
        "additionalProperties": false
      },
      "DeclineProfile": {
        "type": "object",
        "description": "One tool's decline conventions.",
        "required": [
          "id",
          "title",
          "declines",
          "year_days",
          "months",
          "volumes",
          "ratio_slope",
          "verified",
          "verified_against",
          "markdown"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The tool.",
            "enum": [
              "valnav",
              "mosaic",
              "combocurve",
              "novi",
              "aries"
            ]
          },
          "title": {
            "type": "string",
            "description": "The tool's name."
          },
          "declines": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A decline basis.",
              "enum": [
                "nominal",
                "secant",
                "tangent"
              ]
            },
            "description": "The bases the tool's files state declines in: nominal (continuous), secant effective or tangent effective, each a fraction per year."
          },
          "year_days": {
            "type": "number",
            "description": "Days in the year those declines are per."
          },
          "months": {
            "type": "string",
            "description": "calendar for calendar months, 30-day for 30-day months from ip day 0.",
            "enum": [
              "calendar",
              "30-day"
            ]
          },
          "volumes": {
            "type": "string",
            "description": "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.",
            "enum": [
              "integral",
              "start_of_day"
            ]
          },
          "ratio_slope": {
            "type": "string",
            "description": "What ratio segments (GOR, OGR, CGR, WOR, WGR) decline with when a segment doesn't say: time, or the parent stream's cumulative volume.",
            "enum": [
              "time",
              "volume"
            ]
          },
          "verified": {
            "type": "boolean",
            "description": "Whether the tool's own results back these conventions; verified_against says how far."
          },
          "verified_against": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the profile matches, in words; for an unverified one, what it was compared with, or null."
          },
          "markdown": {
            "type": "string",
            "description": "The profile in Markdown."
          }
        },
        "additionalProperties": false
      },
      "FieldDictionary": {
        "type": "object",
        "description": "What fields, export columns and Legacy Forecasts names mean.",
        "required": [
          "api_version",
          "fields",
          "export_columns",
          "model_tables",
          "fe_names"
        ],
        "properties": {
          "api_version": {
            "type": "string",
            "description": "API version."
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A field.",
              "required": [
                "name",
                "schema",
                "type",
                "unit",
                "description"
              ],
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Field name."
                },
                "schema": {
                  "type": "string",
                  "description": "The schema in this document that holds it; a name can appear under several."
                },
                "type": {
                  "type": "string",
                  "description": "Its type without null, as number or as a schema in this document."
                },
                "unit": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The unit its name carries, from a suffix of _ft, _bbl_per_ft or _lb_per_ft. Null when the name carries none; the description then gives any unit."
                },
                "description": {
                  "type": "string",
                  "description": "What it means, as this document says."
                }
              },
              "additionalProperties": false
            },
            "description": "The fields, in schema order."
          },
          "export_columns": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "An export column.",
              "required": [
                "table",
                "file",
                "name",
                "unit",
                "description",
                "default",
                "stream",
                "added_by_plan"
              ],
              "properties": {
                "table": {
                  "type": "string",
                  "description": "Table id.",
                  "enum": [
                    "monthly",
                    "arps",
                    "eur",
                    "wells",
                    "designs",
                    "forecast",
                    "neighbors",
                    "calc_features",
                    "subsurface",
                    "shap",
                    "valnav_decline",
                    "combocurve_wells",
                    "combocurve_forecast",
                    "economics"
                  ]
                },
                "file": {
                  "type": "string",
                  "description": "Its file in the zip."
                },
                "name": {
                  "type": "string",
                  "description": "Column name."
                },
                "unit": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Unit, as bbl or day."
                },
                "description": {
                  "type": "string",
                  "description": "What it holds."
                },
                "default": {
                  "type": "boolean",
                  "description": "Written when the request names no columns."
                },
                "stream": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The stream the column belongs to.",
                  "enum": [
                    "oil",
                    "gas",
                    "water",
                    null
                  ]
                },
                "added_by_plan": {
                  "type": "boolean",
                  "description": "True when GET /export-formats doesn't list it: a plan adds it to the wells table, whatever columns are chosen, when the plan sets what it reports."
                }
              },
              "additionalProperties": false
            },
            "description": "The export columns, table by table."
          },
          "model_tables": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A table.",
              "required": [
                "table",
                "file",
                "description"
              ],
              "properties": {
                "table": {
                  "type": "string",
                  "description": "Table id.",
                  "enum": [
                    "monthly",
                    "arps",
                    "eur",
                    "wells",
                    "designs",
                    "forecast",
                    "neighbors",
                    "calc_features",
                    "subsurface",
                    "shap",
                    "valnav_decline",
                    "combocurve_wells",
                    "combocurve_forecast",
                    "economics"
                  ]
                },
                "file": {
                  "type": "string",
                  "description": "Its file in the zip."
                },
                "description": {
                  "type": "string",
                  "description": "What it holds."
                }
              },
              "additionalProperties": false
            },
            "description": "The tables with no fixed columns: each writes the plan's own."
          },
          "fe_names": {
            "type": "object",
            "description": "Legacy Forecasts names: the output names of Novi's earlier Forecast Engine.",
            "required": [
              "note",
              "not_mapped",
              "groups"
            ],
            "properties": {
              "note": {
                "type": "string",
                "description": "How to read these rows."
              },
              "not_mapped": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A Legacy Forecasts name."
                },
                "description": "Job settings and bookkeeping names, which have no row."
              },
              "groups": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A group of Legacy Forecasts names.",
                  "required": [
                    "title",
                    "note",
                    "rows"
                  ],
                  "properties": {
                    "title": {
                      "type": "string",
                      "description": "Heading."
                    },
                    "note": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "What applies to every row of the group."
                    },
                    "rows": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "One Legacy Forecasts name.",
                        "required": [
                          "name",
                          "fe_tables",
                          "v2",
                          "none",
                          "columns"
                        ],
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "The Legacy Forecasts name."
                          },
                          "fe_tables": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "description": "An output table."
                            },
                            "description": "The output tables that have it."
                          },
                          "v2": {
                            "type": "string",
                            "description": "The field or export column that carries it, in words. A name can map differently per output table; the text says how."
                          },
                          "none": {
                            "type": "boolean",
                            "description": "True when v2 has no field for it in any of those tables. False when one table has one, or v2 has only a near match: v2 then says so."
                          },
                          "columns": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "description": "An export column.",
                              "required": [
                                "table",
                                "name"
                              ],
                              "properties": {
                                "table": {
                                  "type": "string",
                                  "description": "Table id.",
                                  "enum": [
                                    "monthly",
                                    "arps",
                                    "eur",
                                    "wells",
                                    "designs",
                                    "forecast",
                                    "neighbors",
                                    "calc_features",
                                    "subsurface",
                                    "shap",
                                    "valnav_decline",
                                    "combocurve_wells",
                                    "combocurve_forecast",
                                    "economics"
                                  ]
                                },
                                "name": {
                                  "type": "string",
                                  "description": "Column name."
                                }
                              },
                              "additionalProperties": false
                            },
                            "description": "The export columns v2 names; empty when it names only API fields."
                          }
                        },
                        "additionalProperties": false
                      },
                      "description": "Its names."
                    }
                  },
                  "additionalProperties": false
                },
                "description": "The names, grouped."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "MonthlyTable": {
        "type": "object",
        "description": "The monthly table and its options.",
        "required": [
          "table"
        ],
        "properties": {
          "table": {
            "const": "monthly",
            "description": "Monthly volumes: each well's forecast by 30-day month on production, and with horizon eur its EUR's decline to the EUR day."
          },
          "horizon": {
            "type": "string",
            "description": "eur: to the EUR day (the plan's eur_years; needs a plan made with eur: true); forecast: the forecast's months. Defaults to eur on a plan with EUR, else forecast.",
            "enum": [
              "eur",
              "forecast"
            ]
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A value.",
              "enum": [
                "volume",
                "cumulative",
                "rate"
              ]
            },
            "description": "Columns per stream: the month's volume, the cumulative at its end, the average daily rate. Default volume and cumulative.",
            "minItems": 1,
            "maxItems": 200
          },
          "totals": {
            "type": "boolean",
            "description": "Add Plan total rows per design and month at the end. Default true when the export has more than one well."
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A column name from GET /export-formats."
            },
            "description": "Only these columns, in the table's order; absent for its default columns. Not for neighbors, calc_features and subsurface, which write the plan's own columns.",
            "minItems": 1,
            "maxItems": 200
          }
        },
        "additionalProperties": false
      },
      "PlainTable": {
        "type": "object",
        "description": "A table without options.",
        "required": [
          "table"
        ],
        "properties": {
          "table": {
            "type": "string",
            "description": "A table without options: eur (needs a plan made with eur: true), wells, designs, forecast, neighbors, calc_features, subsurface or combocurve_wells, ComboCurve's well header, whose columns are ComboCurve's (columns is a 400).",
            "enum": [
              "eur",
              "wells",
              "designs",
              "forecast",
              "neighbors",
              "calc_features",
              "subsurface",
              "combocurve_wells"
            ]
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A column name from GET /export-formats."
            },
            "description": "Only these columns, in the table's order; absent for its default columns. Not for neighbors, calc_features and subsurface, which write the plan's own columns.",
            "minItems": 1,
            "maxItems": 200
          }
        },
        "additionalProperties": false
      },
      "ArpsTable": {
        "type": "object",
        "description": "The arps table and its options.",
        "required": [
          "table"
        ],
        "properties": {
          "table": {
            "const": "arps",
            "description": "Arps parameters: each forecast curve's multi-segment Arps fit, a row per segment."
          },
          "segments": {
            "type": "integer",
            "description": "Hyperbolic segments before the terminal exponential. Default 2.",
            "minimum": 1,
            "maximum": 4
          },
          "ramp": {
            "type": "boolean",
            "description": "Start with a linear ramp to the peak rate within the first 90 days. Default false."
          },
          "reconcile": {
            "type": "string",
            "description": "forward (the default where this server's worker takes it, else independent): each later segment rescaled so its rate starts where the one before stops; independent: each segment fit on its own. GET /export-formats lists the methods this server's worker takes and the default.",
            "enum": [
              "independent",
              "forward"
            ]
          },
          "b_min": {
            "type": "number",
            "description": "The lowest b the table's hyperbolics may take. Default: the plan's plan-wide `decline` b_min (a wells source's `source.decline`) when the export sends neither bound, else 0.5, also when that b_min is below 0.5; a stream's or layer's bounds don't count.",
            "minimum": 0.5,
            "maximum": 2.5
          },
          "b_max": {
            "type": "number",
            "description": "The highest b the table's hyperbolics may take, above b_min. Default: the plan's plan-wide `decline` b_max (a wells source's `source.decline`) when the export sends neither bound, else 2.5, also when that plan's b_min is below 0.5; a stream's or layer's bounds don't count.",
            "minimum": 0.5,
            "maximum": 2.5
          },
          "exponential_units": {
            "type": "string",
            "description": "The exponential row's declines. annual (default): the terminal decline in d_tangent and d_secant and −ln(1 − terminal decline) in d_nominal, all per year; per_day: d_tangent per day and the others blank.",
            "enum": [
              "annual",
              "per_day"
            ]
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A column name from GET /export-formats."
            },
            "description": "Only these columns, in the table's order; absent for its default columns. Not for neighbors, calc_features and subsurface, which write the plan's own columns.",
            "minItems": 1,
            "maxItems": 200
          }
        },
        "additionalProperties": false
      },
      "ShapTable": {
        "type": "object",
        "description": "The shap table and its options.",
        "required": [
          "table"
        ],
        "properties": {
          "table": {
            "const": "shap",
            "description": "SHAP values: each forecast's feature contributions by stream and ip day, a row per feature. At most 500 forecasts an export."
          },
          "ip_days": {
            "type": "string",
            "description": "all (default): every forecast ip day; last: the last forecast ip day only.",
            "enum": [
              "all",
              "last"
            ]
          },
          "top": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The most features to keep per well, design, stream and ip day, by absolute contribution, the rest summed into one `(other)` row; null (default) keeps every feature.",
            "minimum": 1,
            "maximum": 50
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A column name from GET /export-formats."
            },
            "description": "Only these columns, in the table's order; absent for its default columns. Not for neighbors, calc_features and subsurface, which write the plan's own columns.",
            "minItems": 1,
            "maxItems": 200
          }
        },
        "additionalProperties": false
      },
      "ValNavTable": {
        "type": "object",
        "description": "The valnav_decline table and its options.",
        "required": [
          "table"
        ],
        "properties": {
          "table": {
            "const": "valnav_decline",
            "description": "Val Nav decline: each curve's Arps fit through the last IP day, then rows that total the plan's EUR, as Val Nav's decline CSV, a row per segment. Needs a plan made with eur: true and the worker's Arps fit. Its 17 columns are Val Nav's: columns is a 400."
          },
          "segments": {
            "type": "integer",
            "description": "Hyperbolic rows fitted to the forecast before its last IP day, 1 (default) or 2. With 1 the rows add one more hyperbolic from the last IP day to the terminal decline; with 2 the second runs on to the tail. Either way they total the plan's EUR; 3 or 4 is a 400, since Val Nav's templates take at most two hyperbolic rows before the tail.",
            "minimum": 1,
            "maximum": 2
          },
          "ramp": {
            "type": "boolean",
            "description": "Start with a linear ramp (N −1) to the peak rate within the first 90 days. Default false."
          }
        },
        "additionalProperties": false
      },
      "ComboCurveTable": {
        "type": "object",
        "description": "The combocurve_forecast table and its options.",
        "required": [
          "table"
        ],
        "properties": {
          "table": {
            "const": "combocurve_forecast",
            "description": "ComboCurve forecast parameters: each curve's Arps fit to the forecast's last IP day, then the plan's EUR decline, as ComboCurve's forecast parameters import takes it, a row per segment. Needs a plan made with eur: true and the worker's Arps fit. Its 14 columns are ComboCurve's: columns is a 400."
          },
          "segments": {
            "type": "integer",
            "description": "The fit's hyperbolic segments up to the forecast's last IP day, as the arps table's; then the plan's EUR decline: a hyperbolic row when its switch day is after that day, and its terminal decline. Default 2.",
            "minimum": 1,
            "maximum": 4
          },
          "ramp": {
            "type": "boolean",
            "description": "Start with a linear segment to the peak rate within the first 90 days, as the arps table's. Default false."
          }
        },
        "additionalProperties": false
      },
      "EconomicsTable": {
        "type": "object",
        "description": "The economics table and its options.",
        "required": [
          "table"
        ],
        "properties": {
          "table": {
            "const": "economics",
            "description": "Economics: economics.csv, unrounded NPV, capex, IRR and payback from the P50 forecasts of the streams the plan's model set serves, whatever streams, p_levels or flags say. Needs EUR.\n\n- Rows: wells in plan order, then pads in first-well order (no pad last), then a plan row, per design and scenario in plan order. Pads and plan sum cash flows as if every well came online together.\n- Fixed columns (columns is a 400); null numbers blank; CSV only.\n- manifest.json `economics` echoes the deck and conventions and counts wells, priced and unpriced by reason, over every design and scenario."
          },
          "flows": {
            "type": "string",
            "description": "none writes no cash flows; pads adds economics_flows.csv for pads and plan; wells adds every priced well too. Month 0 is capex; cash_flow_usd and cumulative_usd are unrounded, with row, well, design, scenario and pad identifying each series.",
            "enum": [
              "none",
              "pads",
              "wells"
            ],
            "default": "none"
          }
        },
        "additionalProperties": false
      },
      "ExportTable": {
        "description": "One table of the zip, with its options.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/MonthlyTable"
          },
          {
            "$ref": "#/components/schemas/ArpsTable"
          },
          {
            "$ref": "#/components/schemas/ShapTable"
          },
          {
            "$ref": "#/components/schemas/ValNavTable"
          },
          {
            "$ref": "#/components/schemas/ComboCurveTable"
          },
          {
            "$ref": "#/components/schemas/PlainTable"
          },
          {
            "$ref": "#/components/schemas/EconomicsTable"
          }
        ]
      },
      "ExportPlanSource": {
        "type": "object",
        "description": "A done plan.",
        "required": [
          "plan"
        ],
        "properties": {
          "plan": {
            "type": "string",
            "description": "A done plan's id, from POST /plans.",
            "format": "uuid"
          }
        },
        "additionalProperties": false
      },
      "ExportComparisonSource": {
        "type": "object",
        "description": "A comparison of two done plans or scenarios, written as its tables.",
        "required": [
          "comparison"
        ],
        "properties": {
          "comparison": {
            "type": "object",
            "description": "Two plan sides and what to measure, as POST /comparisons takes them, but without `wells` (the download writes every pair, by a_index) or the pricing fields `deck_id`, `deck`, `conventions` and `include` `value`: each is a 400 here, as is a forecast source side.",
            "required": [
              "a",
              "b"
            ],
            "properties": {
              "a": {
                "$ref": "#/components/schemas/ComparisonSide",
                "description": "Side a, the base: `delta` is b − a and `delta_pct` is relative to it."
              },
              "b": {
                "$ref": "#/components/schemas/ComparisonSide",
                "description": "Side b. It may be the plan of side a, with another scenario or design."
              },
              "metric": {
                "type": "string",
                "description": "The per-well metric distribution, groups and curves measure: eur_boe by default when both sides have EUR, else cum_boe.\n\nPer-well metrics: `eur_oil` (bbl), `eur_gas` (mcf) and `eur_boe` (BOE) are each well's EUR and need a plan made with `eur: true` (400 otherwise); `cum_oil`, `cum_gas` and `cum_boe` are the forecast's cumulative volume at `ip_day`. BOE is oil + gas / 6, only for wells with both.",
                "enum": [
                  "eur_boe",
                  "eur_oil",
                  "eur_gas",
                  "cum_boe",
                  "cum_oil",
                  "cum_gas"
                ]
              },
              "ip_day": {
                "type": "integer",
                "description": "For a cum_ metric, the ip_day to measure, one of the forecast ip_days GET /dataset lists; 1080 by default. With an eur_ metric it is a 400.",
                "minimum": 1
              },
              "normalize_lateral_ft": {
                "type": "number",
                "description": "Scale each well's value to this lateral length in distribution and groups, as GET /plans/{id}/stats does: value × normalize_lateral_ft / its lateral_length_ft. Totals and curves stay unscaled. 100 to 20,000.",
                "minimum": 100,
                "maximum": 20000
              },
              "group_by": {
                "type": "string",
                "description": "Also compare each group of wells: design (every design index either side has), formation (each well's target formation, null for none), scenario (a 400 when neither side's plan has scenarios), or pad (the pad key, null for wells without one; 400 when neither plan has keys). Pads pair by key in side a plan order then new side b keys, null last, without a cap or Other row.",
                "enum": [
                  "design",
                  "formation",
                  "scenario",
                  "pad"
                ]
              },
              "include": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "curves: each side's summed curve for the metric's stream; bands: with curves, each side's summed P10 and P90 (a 400 without curves); wells: paired wells' rows and their summary; inputs: the inputs that changed between paired wells.",
                  "enum": [
                    "curves",
                    "bands",
                    "wells",
                    "inputs"
                  ]
                },
                "description": "Optional parts. Any other value is a 400 listing these."
              },
              "pair": {
                "$ref": "#/components/schemas/ComparisonPairing"
              },
              "horizon": {
                "anyOf": [
                  {
                    "type": "string",
                    "description": "own: each side's EUR only, the default.",
                    "enum": [
                      "own"
                    ]
                  },
                  {
                    "type": "object",
                    "description": "A common horizon: cumulative rows at that many years.",
                    "required": [
                      "years"
                    ],
                    "properties": {
                      "years": {
                        "type": "integer",
                        "description": "Years.",
                        "minimum": 1,
                        "maximum": 50
                      }
                    },
                    "additionalProperties": false
                  }
                ],
                "description": "Each side's cumulative at a common horizon beside its EUR; needs EUR on both sides (a 400 naming the side without)."
              },
              "align": {
                "type": "string",
                "description": "`calendar` adds curves.calendar, each side's curve by calendar month (needs include curves and a well with a TIL date on each side, or a start date on every well of a forecast source side); months_on, the default, adds nothing.",
                "enum": [
                  "months_on",
                  "calendar"
                ]
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "ExportComparisonSide": {
        "type": "object",
        "description": "One side of a comparison export, its defaults filled in.",
        "required": [
          "plan",
          "scenario",
          "design"
        ],
        "properties": {
          "plan": {
            "type": "string",
            "description": "The side's plan id.",
            "format": "uuid"
          },
          "scenario": {
            "type": [
              "string",
              "null"
            ],
            "description": "The side's scenario; null for a plan without scenarios."
          },
          "design": {
            "type": "integer",
            "description": "The design, as its index in `designs`.",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "ExportSourceWell": {
        "type": "object",
        "description": "A well to forecast, as POST /plans takes it, with its label.",
        "required": [
          "shl",
          "bhl"
        ],
        "properties": {
          "shl": {
            "type": "array",
            "description": "Surface hole location, [lng, lat].",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "bhl": {
            "type": "array",
            "description": "Bottom hole (toe) location, [lng, lat]. The lateral runs from heel, else shl, to bhl and must be 100 to 50,000 ft long.",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Target formation (case-insensitive; GET /formations lists them). Needed to forecast and to estimate TVD."
          },
          "tvd_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 40000
          },
          "landing_below_top_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's `subsurface_sampling` (GET /model-sets).",
            "exclusiveMinimum": -40000,
            "exclusiveMaximum": 40000
          },
          "heel": {
            "type": [
              "array",
              "null"
            ],
            "description": "Where the lateral starts, [lng, lat], when not at `shl`, the surface hole; absent or null, it starts at `shl`. `shl` must be within 50,000 ft of it.\n\nWith it, the lateral length and its 100 to 50,000 ft check, spacing, gun barrel laterals, PDP wells and model analogs run from heel to bhl. Subsurface grids still sample at `shl` and `bhl` as the set's `subsurface_sampling` says, and structure tops, landing, TVD estimates, the KB elevation and the model's surface hole inputs stay at `shl`.",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "typed_lateral": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TypedLateral"
              },
              {
                "type": "null"
              }
            ],
            "description": "A lateral length typed for the well, as an inventory file gives it: `length_ft`, and the `heel` (the well's heel, else its `shl`) and `bhl` it was typed for.\n\nThe model gets `length_ft` as `novi_lateral_length`, and spacing, the completion totals, analogs, normalize_lateral_ft and pricing use it, while the well's heel (else shl) and bhl equal those two exactly and it is within 5% of the length measured between them or within 100 to 50,000 ft; otherwise the measured length. A client that moves an end can send it unchanged: the well then uses the measured length.\n\nReads give the length used as `lateral_length_ft`, with `lateral_length_source`. Optional: absent or null, the measured length.\n\nPOST /inventories/read sets it from a file's stated length unless that is both more than 5% off the drawn one and outside 100 to 50,000 ft, with an issue when it is more than 5% off."
          },
          "landing_fraction": {
            "type": [
              "number",
              "null"
            ],
            "description": "Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.\n\nThe top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.\n\nThe rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.\n\nTop and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.\n\nNeeds formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:\n\n- its formation has no grid there or no place in the column;\n- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);\n- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;\n- top and base averaged over the ends are under a foot apart: the zone pinches out.\n\nA well's inputs echo it when it was sent.",
            "minimum": 0,
            "maximum": 1
          },
          "lateral_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Ignored, as in POST /plans."
          },
          "pad": {
            "type": [
              "number",
              "string",
              "null"
            ],
            "description": "The pad the well is on: a whole number, as POST /layouts/fill numbers them, or text of 1 to 60 characters, trimmed; 1 and \"1\" are one pad.\n\nPOST /plans keeps a valid key whenever sent, for `group_by=pad` and the `pad=` filter, and doesn't echo it on wells; other requests read it only with `pads`. It is checked (a 400 on a bad value) only with `pads`; without `pads`, a value that isn't a pad is ignored."
          },
          "scenario": {
            "type": "string",
            "description": "As in POST /plans: every well has one or none, at most 20; then the export's `scenario` picks one.",
            "minLength": 1,
            "maxLength": 60
          },
          "fluid_bbl_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "This well's fluid in bbl per lateral ft.\n\nEach field takes the narrowest layer that sets it, on its own: the well, its pad's entry in `pads` or its layout (the bench or formation entry, then overall), its entry in `scenarios` (formation entry, then overall), the design's `formations` entry for its formation, the design, then the default: the recent-completions median of the well's formation, else the play's.\n\nNeeds one design or none; with more, the request is a 400 naming the well. POST /gun-barrels refuses it. Sending one adds `resolved` to every well's `inputs` in the request.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 1000
          },
          "proppant_lb_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "This well's proppant in lb per lateral ft.\n\nEach field takes the narrowest layer that sets it, on its own: the well, its pad's entry in `pads` or its layout (the bench or formation entry, then overall), its entry in `scenarios` (formation entry, then overall), the design's `formations` entry for its formation, the design, then the default: the recent-completions median of the well's formation, else the play's.\n\nNeeds one design or none; with more, the request is a 400 naming the well. POST /gun-barrels refuses it. Sending one adds `resolved` to every well's `inputs` in the request.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 20000
          },
          "stage_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Stage length in ft.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 2000
          },
          "clusters_per_stage": {
            "type": [
              "number",
              "null"
            ],
            "description": "Perforation clusters per stage; fractions are accepted.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 100
          },
          "frac_rate_bbl_per_min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Frac pump rate in bbl per minute.\n\nRead only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's `unused`. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.",
            "exclusiveMinimum": 0,
            "exclusiveMaximum": 500
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings",
            "description": "EUR settings for this well; needs `eur` on.\n\nWith `eur` off, a `decline` on any layer is a 400, even `{}` or one that reaches no well, though either sets nothing. POST /exports `source` turns `eur` on when it is left out.\n\nEach field takes the narrowest value set: the well's; its pad's or layout's, `formations` entry or bench first; its scenario's, `formations` entry first; the request's `formations` entry; the request's `decline`; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's `b_max` beats a plan's `oil.b_max`. Once a value reaches a well, every well's `inputs.resolved.decline` gives each value and its layer, and the export's wells table adds them.\n\nA well whose `b_min` resolves at or above its `b_max` is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics `forecast` refuse a `decline`."
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "description": "The well's name in every table (the well column). Default Drawn well for one drawn well, else Well 1, Well 2, …; each well's must differ.",
            "maxLength": 100
          }
        },
        "additionalProperties": false
      },
      "ExportWellsSource": {
        "type": "object",
        "description": "Wells the export forecasts first, in a plan of its own.",
        "required": [
          "kind",
          "wells"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "description": "What the wells are, which names the file: drawn (drawn-well-…), pad (pad-…) or optimizer (optimizer-…).",
            "enum": [
              "drawn",
              "pad",
              "optimizer"
            ]
          },
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportSourceWell"
            },
            "description": "The wells; up to limits.max_source_wells forecasts (500 by default; GET /export-formats reports this server's) divided by the number of designs.",
            "minItems": 1,
            "maxItems": 500
          },
          "designs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignInput"
            },
            "description": "Completion designs; every well is forecast with each. Leave out for one design at the recent-completions median. A well's own completions, a scenario's and a pad's or layout's need one design.",
            "minItems": 1,
            "maxItems": 10
          },
          "scenarios": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScenarioInput"
            },
            "description": "Values for each scenario's wells, keyed by the `scenario` the wells name; a scenario without an entry takes the request's values.\n\nA well's own completions, `til_date` and landing beat its scenario's, as do its pad's and its layout's or bench's. A scenario's completions beat the design's, and its `til_date` and `pdp` the request's. Once an entry sets completions, every well's `inputs.resolved` gives them. Once one sets a TIL date or landing that a well takes, `inputs.resolved` gives each well's `til_date` and `landing`, and the export's wells table adds `til_date`, `til_layer` and `landing_layer`.\n\nA 400 naming the entry refuses a name no well has, a repeated name, `scenarios` when no well has a scenario, and completions in it under more than one design.",
            "minItems": 1,
            "maxItems": 20
          },
          "pads": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PadInput"
            },
            "description": "Values for each pad's wells, keyed by the `pad` the wells name; a well on no listed pad takes the layers below. An entry may hold only `pad` and `name`.\n\nA well's own completions, `til_date` and landing beat its pad's, an entry's `formations` beat its own values, and a pad beats its wells' scenarios. Once an entry sets completions, every well's `inputs.resolved` gives them. Once one sets a TIL date or landing that a well takes, `inputs.resolved` gives each well's `til_date` and `landing`, and the export's wells table adds `til_date`, `til_layer` and `landing_layer`.\n\nA 400 naming the field refuses:\n\n- a pad no well has, or a repeat (1 and \"1\" are one pad);\n- a bad `pad` on any well;\n- over 200,000 `formations` entries across the list;\n- `pads` with `layout` or `layouts`, whose own fields set their wells;\n- a well with no formation that takes `landing_below_top_ft` or `landing_fraction` from an entry's own values;\n- completions in it under more than one design.",
            "minItems": 1
          },
          "formations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormationLandingInput"
            },
            "description": "The request's landing per formation, each formation at most once; a landing on the well, its pad, layout, bench or scenario entry beats it. Goes with `wells`.\n\nAn entry for a formation no well has is accepted. Completions per formation stay in `designs`. Once an entry sets a landing that a well takes, `inputs.resolved` gives each well's `til_date` and `landing`, and the export's wells table adds `til_date`, `til_layer` and `landing_layer`.",
            "maxItems": 100
          },
          "til_date": {
            "type": "string",
            "description": "TIL date, YYYY-MM-DD, for every well no narrower layer dates, as POST /plans takes it.",
            "format": "date"
          },
          "pdp": {
            "type": "boolean",
            "default": true,
            "description": "Space against existing (PDP) wells. A scenario's `pdp` in `scenarios` beats it, and this stays the manifest's `pdp`."
          },
          "eur": {
            "type": "boolean",
            "description": "Fit EUR for monthly volumes to EUR and the EUR summary. Default true when the server has EUR (GET /dataset eur.available; when the forecast worker doesn't answer within 1.5 s, its last ready answer, else a 503), or when decline is sent at any layer or eur_water is true; true answers 503 without it."
          },
          "eur_water": {
            "type": "boolean",
            "default": false,
            "description": "Fit water's EUR too, with `decline.water` over the settings at any layer.\n\nAdds `eur` to each water forecast, `water` to the `decline` echo, `totals[].eur` and `inputs.resolved.decline`, and water's columns to the eur, forecast and wells tables, where monthly water runs to the EUR day. BOE never reads it, and oil's and gas's fits are unchanged. Without it, `decline.water` is a 400. With `eur` left out it turns EUR on, as `decline` does; with `eur: false` it is a 400 on source.eur_water."
          },
          "decline": {
            "$ref": "#/components/schemas/DeclineSettings",
            "description": "Decline fit settings, as on POST /plans."
          },
          "depletion_chain": {
            "type": "boolean",
            "description": "Chain depletion in the export's plan, as POST /plans' `depletion_chain` does: on by default where GET /dataset `depletion_chain.available` is true, else off, and `false` turns it off. The export's `source.depletion_chain` echoes it where the plan would."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "A name for the wells, as a plan name: the export's title when it has none.",
            "maxLength": 100
          }
        },
        "additionalProperties": false
      },
      "ExportCallback": {
        "type": "object",
        "description": "One callback URL and its delivery.",
        "required": [
          "url",
          "status",
          "attempts",
          "last_status",
          "last_error",
          "delivered_at"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "Where it goes: its origin, with /… for any path or query. The server keeps the whole URL, for delivery only."
          },
          "status": {
            "type": "string",
            "description": "pending until delivered or failed; a cancelled export's pending callbacks fail with no attempts, since nothing is sent.",
            "enum": [
              "pending",
              "delivered",
              "failed"
            ]
          },
          "attempts": {
            "type": "integer",
            "description": "POSTs so far.",
            "minimum": 0
          },
          "last_status": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The receiver's last HTTP status."
          },
          "last_error": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why the last attempt failed."
          },
          "delivered_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When a 2xx came back.",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "ExportRequest": {
        "type": "object",
        "description": "Export request: preset or tables, or neither for the plan's default preset.",
        "required": [
          "source"
        ],
        "properties": {
          "source": {
            "description": "What to export: a done plan, wells to forecast first, or a comparison of two plans.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/ExportPlanSource"
              },
              {
                "$ref": "#/components/schemas/ExportWellsSource"
              },
              {
                "$ref": "#/components/schemas/ExportComparisonSource"
              }
            ]
          },
          "preset": {
            "type": "string",
            "description": "A preset id from GET /export-formats, as engineer. Not with tables."
          },
          "tables": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportTable"
            },
            "description": "The tables to write, each once, with their options. Not with preset.",
            "minItems": 1,
            "maxItems": 14
          },
          "wells": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "integer",
              "description": "A plan well index from 0.",
              "minimum": 0
            },
            "minItems": 1,
            "maxItems": 100000,
            "description": "Only these plan wells, by index in the plan (repeats count once); null or absent for all of them. Up to 10,000 indexes, or as many as the plan has wells when it has more."
          },
          "designs": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "integer",
              "description": "A design index from 0.",
              "minimum": 0
            },
            "minItems": 1,
            "maxItems": 10000,
            "description": "Only these designs, by index in the plan (repeats count once); null or absent for all of them."
          },
          "scenario": {
            "type": "string",
            "description": "Instead of wells: only this scenario's wells, of a plan (or source wells) made with scenarios; a 400 with wells, on a plan without scenarios, or naming none of its scenarios (details.scenarios lists them).",
            "minLength": 1,
            "maxLength": 60
          },
          "streams": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Stream.",
              "enum": [
                "oil",
                "gas",
                "water"
              ]
            },
            "description": "Only these streams' columns (default all three).",
            "minItems": 1,
            "maxItems": 200
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your name for the export; the zip's file name is this plus .zip.",
            "maxLength": 100
          },
          "callback_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Where to POST the export once it is done or fails: https, to a host the server allows (GET /export-formats callbacks).",
            "maxLength": 2048
          },
          "parquet": {
            "type": "boolean",
            "default": true,
            "description": "Also write fixed-schema tables as Parquet under parquet/, with export_id and Snowflake and Databricks load scripts. Tables whose GET /export-formats `parquet` is false are CSV only. true with preset aries is a 400 (a text file)."
          },
          "p_levels": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A P-level.",
              "enum": [
                "P50",
                "P10",
                "P90"
              ]
            },
            "description": "The P-levels the monthly, eur, arps, valnav_decline and combocurve_forecast tables write, a row each (P50, P10, P90), and the blocks preset aries writes. Default P50 alone, even on a plan with bands.\n\nP10 and P90 need a plan made with bands: true (409 without); p_levels needs a table with P-levels or preset aries (400 without). combocurve_forecast writes each as a series: P50 as best, Novi's P10 (low) as P90, its P90 (high) as P10; combocurve_wells writes none. P10 is the low curve and P90 the high one, Novi's convention; SPE PRMS uses the reverse (its P90 is the low, proved case).",
            "minItems": 1,
            "maxItems": 200
          },
          "aries": {
            "$ref": "#/components/schemas/AriesOptions"
          },
          "identity": {
            "$ref": "#/components/schemas/ExportIdentity"
          },
          "reserves_categories": {
            "type": "object",
            "description": "With preset valnav or the valnav_decline table only (400 otherwise): the Rescat Val Nav's file writes per P-level; P50's replaces identity.reserves_category.\n\nP10 and P90 each need their own when p_levels sends them (two on one category is a 400); a level not in p_levels is a 400 naming it. Novi never maps P-levels to 1P, 2P or 3P: its P10 is the low curve, PRMS's P90.",
            "required": [],
            "properties": {
              "P50": {
                "type": "string",
                "description": "P50's reserves category: 1 to 40 characters with no control characters.",
                "minLength": 1,
                "maxLength": 40
              },
              "P10": {
                "type": "string",
                "description": "P10's reserves category: 1 to 40 characters with no control characters.",
                "minLength": 1,
                "maxLength": 40
              },
              "P90": {
                "type": "string",
                "description": "P90's reserves category: 1 to 40 characters with no control characters.",
                "minLength": 1,
                "maxLength": 40
              }
            },
            "additionalProperties": false
          },
          "combocurve": {
            "type": "object",
            "description": "With preset combocurve or its tables only (400 otherwise): what ComboCurve's forecast parameters file keys each well on, for the second pass. Part of the export's key.",
            "required": [],
            "properties": {
              "inpt_ids": {
                "type": "object",
                "additionalProperties": {
                  "type": "string",
                  "description": "The INPT ID ComboCurve gave the well: 1 to 64 characters, no control characters or line separators.",
                  "minLength": 1,
                  "maxLength": 64
                },
                "description": "Each Well ID's INPT ID, from the ComboCurve project's well list once combocurve_wells.csv is loaded, keyed by the Well IDs (Chosen IDs) in this export. Wells left out keep their Well ID as INPT ID.\n\nA 400 names the entry for an unknown key, a repeated value (compared as written, a lone surrogate as U+FFFD), a control character, or a left-out well's Well ID as value."
              }
            },
            "additionalProperties": false
          },
          "economics": {
            "type": "object",
            "description": "With the economics table or preset only (else a 400 on economics). deck_id, deck and conventions as POST /economics takes them; left out, the plan model set's default deck and prototype conventions.\n\nfe counts with monthly discounting and whole-month payback. The resolved deck and conventions, defaults included, are part of the export key.",
            "required": [],
            "properties": {
              "deck_id": {
                "type": "string",
                "description": "The deck to price with, one GET /economics/decks lists for the set; left out, the set's default deck (prototype-midland-flat; illustrative-haynesville-gas on a Haynesville set).",
                "enum": [
                  "prototype-midland-flat",
                  "house-70-3",
                  "illustrative-haynesville-gas"
                ]
              },
              "deck": {
                "type": "object",
                "description": "Overrides of the deck's values for this request (every deck takes the same ranges); any left out keep the deck's.",
                "required": [],
                "properties": {
                  "oil_price": {
                    "type": "number",
                    "description": "$/bbl; 75 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 300
                  },
                  "oil_differential": {
                    "type": "number",
                    "description": "$/bbl; 4 in the illustrative Midland deck.",
                    "minimum": -50,
                    "maximum": 50
                  },
                  "gas_price": {
                    "type": "number",
                    "description": "$/mcf; 3.5 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 50
                  },
                  "gas_differential": {
                    "type": "number",
                    "description": "$/mcf; 1 in the illustrative Midland deck.",
                    "minimum": -10,
                    "maximum": 10
                  },
                  "ngl_price": {
                    "type": "number",
                    "description": "$/bbl; 26 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 200
                  },
                  "ngl_yield_bbl_per_mmcf": {
                    "type": "number",
                    "description": "bbl/MMcf; 130 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 300
                  },
                  "shrink": {
                    "type": "number",
                    "description": "fraction; 0.8 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 1
                  },
                  "opex_oil": {
                    "type": "number",
                    "description": "$/bbl; 5.5 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "opex_gas": {
                    "type": "number",
                    "description": "$/mcf; 0.5 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 20
                  },
                  "opex_water": {
                    "type": "number",
                    "description": "$/bbl; 0.6 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 20
                  },
                  "royalty": {
                    "type": "number",
                    "description": "fraction; 0.25 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 0.5
                  },
                  "severance_oil": {
                    "type": "number",
                    "description": "fraction; 0.046 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 0.5
                  },
                  "severance_gas": {
                    "type": "number",
                    "description": "fraction; 0.075 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 0.5
                  },
                  "ad_valorem": {
                    "type": "number",
                    "description": "fraction; 0.025 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 0.2
                  },
                  "capex_per_well": {
                    "type": "number",
                    "description": "$; 2500000 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 50000000
                  },
                  "capex_drilling_per_ft": {
                    "type": "number",
                    "description": "$/ft; 150 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 2000
                  },
                  "capex_stimulation_per_ft": {
                    "type": "number",
                    "description": "$/ft; 125 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 2000
                  },
                  "capex_proppant_per_lb": {
                    "type": "number",
                    "description": "$/lb; 0.08 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 2
                  },
                  "capex_fluid_per_bbl": {
                    "type": "number",
                    "description": "$/bbl; 3 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 50
                  },
                  "discount_rate": {
                    "type": "number",
                    "description": "fraction per year; 0.25 in the illustrative Midland deck.",
                    "minimum": 0,
                    "maximum": 1
                  }
                },
                "additionalProperties": false
              },
              "conventions": {
                "type": "string",
                "description": "How NPV and payback are counted: prototype, yearly discounting (the app's default), or fe, monthly discounting, which matches Novi's earlier Forecast Engine.",
                "enum": [
                  "prototype",
                  "fe"
                ],
                "default": "prototype"
              }
            },
            "additionalProperties": false
          },
          "flags": {
            "type": "boolean",
            "default": false,
            "description": "With `preset`, or neither (the default preset): true adds `flagged` and `out_of_range` columns to the preset's eur, wells and forecast tables. Default false.\n\n`flagged`: whether a design's inputs (in wells, any exported design's) fall outside the model's training data. `out_of_range`: each such input with its value and range. GET /export-formats describes both.\n\n- They follow the other columns (on a plan's wells table, before its layer columns and `scenario`), in CSV, and in Parquet for eur and wells; nothing else changes.\n- The export and manifest.json echo `flags: true`; their eur, wells and forecast tables list the resolved `columns`.\n- With `tables`, true is a 400 (list both in each table's `columns`), as is a preset with none of those tables (aries)."
          }
        },
        "additionalProperties": false,
        "not": {
          "description": "preset with tables.",
          "required": [
            "preset",
            "tables"
          ],
          "properties": {
            "preset": true,
            "tables": true
          }
        }
      },
      "ExportJob": {
        "type": "object",
        "description": "An export.",
        "required": [
          "id",
          "status",
          "created_at",
          "started_at",
          "finished_at",
          "seconds",
          "source",
          "name",
          "preset",
          "tables",
          "wells",
          "designs",
          "streams",
          "parquet",
          "queue_position",
          "progress",
          "file",
          "error",
          "callbacks",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Export id.",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "description": "queued, running, then done, error or cancelled; expired once a done export's file is removed.",
            "enum": [
              "queued",
              "running",
              "done",
              "error",
              "cancelled",
              "expired"
            ]
          },
          "reused": {
            "type": "boolean",
            "description": "POST /exports only: true when this is an identical export the server already had."
          },
          "created_at": {
            "type": "string",
            "description": "When it was requested.",
            "format": "date-time"
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When it started running.",
            "format": "date-time"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When it finished, failed or was cancelled.",
            "format": "date-time"
          },
          "seconds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Run time so far, or in total once finished; null until it starts."
          },
          "source": {
            "type": "object",
            "description": "The plan, wells or comparison exported.",
            "required": [
              "kind",
              "plan",
              "name",
              "wells",
              "designs"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "description": "plan, the kind a wells source named, or comparison.",
                "enum": [
                  "plan",
                  "drawn",
                  "pad",
                  "optimizer",
                  "comparison"
                ]
              },
              "plan": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Plan id; null for a wells source, whose plan is the export's own, and for a comparison, whose plans are in comparison.",
                "format": "uuid"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Plan name, or the wells source's; for a comparison, each side's plan name (and scenario) joined by vs."
              },
              "wells": {
                "type": "integer",
                "description": "Wells in the plan; for a comparison, both sides' wells added."
              },
              "designs": {
                "type": "integer",
                "description": "Designs in the plan; for a comparison, 2, a design per side."
              },
              "depletion_chain": {
                "$ref": "#/components/schemas/DepletionChainEcho",
                "description": "A wells source's chain, where POST /plans would echo it for the same request: what it read and did, as GET /plans/{id} shows it. Never on a plan source."
              },
              "comparison": {
                "type": "object",
                "description": "Only on a comparison export: its two sides.",
                "required": [
                  "a",
                  "b"
                ],
                "properties": {
                  "a": {
                    "$ref": "#/components/schemas/ExportComparisonSide"
                  },
                  "b": {
                    "$ref": "#/components/schemas/ExportComparisonSide"
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "The export's name, as requested."
          },
          "preset": {
            "type": [
              "string",
              "null"
            ],
            "description": "The preset it ran, or null for tables."
          },
          "tables": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportTable"
            },
            "description": "The tables written, with every option resolved."
          },
          "wells": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "integer",
              "description": "Plan well index."
            },
            "description": "The plan wells (or source wells) exported, or null for all."
          },
          "designs": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "integer",
              "description": "Design index."
            },
            "description": "The designs exported, or null for all."
          },
          "streams": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Stream.",
              "enum": [
                "oil",
                "gas",
                "water"
              ]
            },
            "description": "The streams exported.",
            "minItems": 1,
            "maxItems": 200
          },
          "parquet": {
            "type": "boolean",
            "description": "Whether this export includes Parquet and load scripts."
          },
          "p_levels": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A P-level.",
              "enum": [
                "P50",
                "P10",
                "P90"
              ]
            },
            "description": "The P-levels written, when they are more than P50.",
            "minItems": 1,
            "maxItems": 200
          },
          "aries": {
            "$ref": "#/components/schemas/AriesSettings"
          },
          "identity": {
            "type": "object",
            "description": "With preset valnav or combocurve, or their tables: the identity the files were written with, every field they read resolved, so requests sent with or without the defaults echo alike; reserves_category with Val Nav only.",
            "required": [
              "well_id",
              "start_date"
            ],
            "properties": {
              "well_id": {
                "type": "string",
                "description": "name, id or uid, as identity.well_id resolved (when left out, name; on a Legacy Forecast, id).",
                "enum": [
                  "name",
                  "id",
                  "uid"
                ]
              },
              "start_date": {
                "type": "string",
                "description": "til, or the date identity.start_date sent, as YYYY-MM-DD."
              },
              "reserves_category": {
                "type": "string",
                "description": "With Val Nav only, since ComboCurve's files carry none: P50's Rescat: reserves_categories' P50 entry when sent, else identity.reserves_category, else PUD."
              }
            },
            "additionalProperties": false
          },
          "reserves_categories": {
            "type": "object",
            "description": "Only when the request sent reserves_categories for P10 or P90: their Rescat, as sent. A P50 entry becomes identity.reserves_category, echoed there.",
            "required": [],
            "properties": {
              "P50": {
                "type": "string",
                "description": "P50's reserves category: 1 to 40 characters with no control characters.",
                "minLength": 1,
                "maxLength": 40
              },
              "P10": {
                "type": "string",
                "description": "P10's reserves category: 1 to 40 characters with no control characters.",
                "minLength": 1,
                "maxLength": 40
              },
              "P90": {
                "type": "string",
                "description": "P90's reserves category: 1 to 40 characters with no control characters.",
                "minLength": 1,
                "maxLength": 40
              }
            },
            "additionalProperties": false
          },
          "combocurve": {
            "type": "object",
            "description": "Only when the request sent combocurve.inpt_ids with an entry.",
            "required": [
              "inpt_ids"
            ],
            "properties": {
              "inpt_ids": {
                "type": "integer",
                "description": "How many INPT IDs the request sent, not the IDs.",
                "minimum": 1
              }
            },
            "additionalProperties": false
          },
          "flags": {
            "type": "boolean",
            "description": "Only when the request sent `flags: true`: the preset's eur, wells and forecast tables list `flagged` and `out_of_range` in `columns`. To repeat the export, send the same `preset` with `flags: true`."
          },
          "queue_position": {
            "type": [
              "integer",
              "null"
            ],
            "description": "While queued, its place in its lane's queue from 1; else null.",
            "minimum": 1
          },
          "progress": {
            "type": "object",
            "description": "Progress.",
            "required": [
              "step",
              "fraction",
              "rows",
              "rows_total",
              "bytes"
            ],
            "properties": {
              "step": {
                "type": "string",
                "description": "queued, then forecast, arps, explain, economics or writing while running (writing covers an aries export's worker calls), then done.",
                "enum": [
                  "queued",
                  "forecast",
                  "arps",
                  "explain",
                  "economics",
                  "writing",
                  "done"
                ]
              },
              "fraction": {
                "type": "number",
                "description": "Share of the step's work done; writing starts again near 0 after the steps before it reach 1.\n\n- arps reaches 1 when its fits finish, explain when every forecast is explained, economics when every design and scenario is priced.\n- writing: CSV rows written, or with Parquet tables 0.9 for the CSV rows and the rest as Parquet files go into the zip; with preset aries, the worker's slices to 0.9, then the file. Below 1 until the export is done.",
                "minimum": 0,
                "maximum": 1
              },
              "rows": {
                "type": "integer",
                "description": "Rows written so far."
              },
              "rows_total": {
                "type": "integer",
                "description": "Rows the export writes, as estimated at the start."
              },
              "bytes": {
                "type": "integer",
                "description": "Bytes written so far."
              }
            },
            "additionalProperties": false
          },
          "file": {
            "anyOf": [
              {
                "type": "object",
                "description": "The zip.",
                "required": [
                  "name",
                  "bytes",
                  "sha256",
                  "url",
                  "expires_at",
                  "entries"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The zip's file name."
                  },
                  "bytes": {
                    "type": "integer",
                    "description": "Size."
                  },
                  "sha256": {
                    "type": "string",
                    "description": "SHA-256 of the zip, hex.",
                    "pattern": "^[0-9a-f]{64}$"
                  },
                  "url": {
                    "type": "string",
                    "description": "Its download URL (GET /exports/{id}/file)."
                  },
                  "expires_at": {
                    "type": "string",
                    "description": "When the file is removed.",
                    "format": "date-time"
                  },
                  "entries": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "A table's file.",
                      "required": [
                        "name",
                        "rows",
                        "bytes"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "CSV or parquet/ file in the zip."
                        },
                        "rows": {
                          "type": "integer",
                          "description": "Data rows."
                        },
                        "bytes": {
                          "type": "integer",
                          "description": "Uncompressed size."
                        }
                      },
                      "additionalProperties": false
                    },
                    "description": "The CSV and Parquet table files in the zip; load/ scripts, manifest.json and README.txt are also included."
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "Once done, the zip; null otherwise."
          },
          "error": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ErrorBody"
              },
              {
                "type": "null"
              }
            ],
            "description": "Why the export failed; a wells source's forecast errors name their field under source."
          },
          "callbacks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportCallback"
            },
            "description": "Its callback URLs and their deliveries.",
            "maxItems": 5
          },
          "links": {
            "type": "object",
            "description": "Related URLs.",
            "required": [
              "self",
              "file"
            ],
            "properties": {
              "self": {
                "type": "string",
                "description": "This export."
              },
              "file": {
                "type": "string",
                "description": "Its zip."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "AriesOptions": {
        "type": "object",
        "description": "With preset aries only (400 otherwise): its options, each with a default.",
        "required": [],
        "properties": {
          "compat": {
            "type": "string",
            "description": "fixed: the layout Novi's earlier Forecast Engine writes, repairing only what is malformed in that layout (duplicate or over-long qualifiers, nan and 100.0 declines, control characters, a failed refit window); fe: that layout byte for byte, defects included.",
            "enum": [
              "fixed",
              "fe"
            ],
            "default": "fixed"
          },
          "major_stream": {
            "type": "string",
            "description": "The stream each block writes first; a block without it is left out, with a note. The default is oil, or gas on a model set without oil; a stream the set doesn't serve is a 400, and on a set serving neither, ARIES is unavailable.",
            "enum": [
              "oil",
              "gas"
            ],
            "default": "oil"
          },
          "well_key": {
            "type": "string",
            "description": "What heads each well: its name, or its id (its key, as DRAWN-0). api is a 400: planned wells have no API numbers.",
            "enum": [
              "name",
              "api",
              "id"
            ],
            "default": "name"
          },
          "start_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "Every well's START month, instead of its TIL date (the plan's start day without one); from 1900-01-01 to 2199-12-31.",
            "format": "date",
            "default": null
          },
          "clean": {
            "type": "boolean",
            "default": true,
            "description": "Control characters (C0, C1) and line separators in well, design and plan names become spaces. false writes them raw and needs compat fe: compat fixed always cleans (400)."
          },
          "last_window": {
            "type": "string",
            "description": "How a stream's last refit window is written when fewer than 12 months follow the last whole one: overlap (the default) writes 12 months that overlap the window before; remaining writes only the months left.\n\nremaining uses the 12-month refit's b and the yearly decline at which those months carry the forecast's volume, and needs compat fixed (a 400 with fe). Where the refit fails, or no decline to 2 decimals carries that volume within 1% (a rising tail, say), it writes the months' mean as a flat line, and a negative mean ends the stream there. Resolved settings list it only when remaining.",
            "enum": [
              "overlap",
              "remaining"
            ],
            "default": "overlap"
          }
        },
        "additionalProperties": false
      },
      "AriesSettings": {
        "type": "object",
        "description": "For preset aries: its options, resolved.",
        "required": [
          "compat",
          "major_stream",
          "well_key",
          "start_date",
          "clean"
        ],
        "properties": {
          "compat": {
            "type": "string",
            "description": "fixed: the layout Novi's earlier Forecast Engine writes, repairing only what is malformed in that layout (duplicate or over-long qualifiers, nan and 100.0 declines, control characters, a failed refit window); fe: that layout byte for byte, defects included.",
            "enum": [
              "fixed",
              "fe"
            ],
            "default": "fixed"
          },
          "major_stream": {
            "type": "string",
            "description": "The stream each block writes first; a block without it is left out, with a note. The default is oil, or gas on a model set without oil; a stream the set doesn't serve is a 400, and on a set serving neither, ARIES is unavailable.",
            "enum": [
              "oil",
              "gas"
            ],
            "default": "oil"
          },
          "well_key": {
            "type": "string",
            "description": "What heads each well: its name, or its id (its key, as DRAWN-0). api is a 400: planned wells have no API numbers.",
            "enum": [
              "name",
              "api",
              "id"
            ],
            "default": "name"
          },
          "start_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "Every well's START month, instead of its TIL date (the plan's start day without one); from 1900-01-01 to 2199-12-31.",
            "format": "date",
            "default": null
          },
          "clean": {
            "type": "boolean",
            "default": true,
            "description": "Control characters (C0, C1) and line separators in well, design and plan names become spaces. false writes them raw and needs compat fe: compat fixed always cleans (400)."
          },
          "last_window": {
            "type": "string",
            "description": "How a stream's last refit window is written when fewer than 12 months follow the last whole one: overlap (the default) writes 12 months that overlap the window before; remaining writes only the months left.\n\nremaining uses the 12-month refit's b and the yearly decline at which those months carry the forecast's volume, and needs compat fixed (a 400 with fe). Where the refit fails, or no decline to 2 decimals carries that volume within 1% (a rising tail, say), it writes the months' mean as a flat line, and a negative mean ends the stream there. Resolved settings list it only when remaining.",
            "enum": [
              "overlap",
              "remaining"
            ],
            "default": "overlap"
          }
        },
        "additionalProperties": false
      },
      "ExportIdentity": {
        "type": "object",
        "description": "Well ID, start date and reserves category for the economics presets; only a preset or table that reads a field takes it.\n\nGET /export-formats?include=identity lists the fields of each preset (presets[].identity) and table (tables[].identity): valnav_decline reads all three, the combocurve tables well_id and start_date.\n\n- With tables, a field none of them lists is a 400 naming it.\n- With another preset, or tables none of which reads identity, it is a 400 naming the presets and tables that do; a planned preset first answers that it isn't available yet.\n- Not an object, or an unknown field: a 400 listing the three.\n- With preset aries it resolves into aries's options before the export is keyed, so a request with identity or with aries shares one export (the second answers reused: true); the job echoes aries alone.\n- With valnav and combocurve it is resolved, defaults filled, so a request with or without the defaults shares one export; the job echoes it resolved.",
        "required": [],
        "properties": {
          "well_id": {
            "type": "string",
            "description": "Each well's Well ID: name (the default) writes its name, else its plan label (Plan well N); id its plan well id, as DRAWN-0; uid its `well_uid` from GET /plans/{id}/curves.\n\n- On a Legacy Forecast the default is id, its unique well key: a run's well names can repeat.\n- uid is 32 characters, the same on every read of the plan, so plans whose wells share names or ids get different Well IDs.\n- With preset aries it is aries.well_key: send either, or the same value in both (null counts as not sent); different values are a 400 naming both.\n- A 400 naming identity.well_id: id or uid on a plan well without an id, name on a well whose name has no visible character, uid with preset aries or on wells sent in `source` (a new plan each export).",
            "enum": [
              "name",
              "id",
              "uid"
            ],
            "default": "name"
          },
          "start_date": {
            "type": "string",
            "description": "Each well's start date: til (the default) writes its TIL date, else the plan's day; a real day as YYYY-MM-DD, 1900-01-01 to 2199-12-31, sets that day for every well.\n\nAnything else is a 400 naming identity.start_date. With preset aries it is aries.start_date (til as null or left out): send either, or the same value in both (null counts as not sent); different values are a 400 naming both.",
            "pattern": "^(til|\\d{4}-\\d{2}-\\d{2})$",
            "default": "til"
          },
          "reserves_category": {
            "type": "string",
            "description": "The reserves category written for every well, 1 to 40 characters with no control characters, PUD when left out. Only presets that write one read it: valnav writes it as Rescat (for P50; reserves_categories names P10's and P90's); ARIES and ComboCurve write none, so with preset aries or combocurve it is a 400.",
            "minLength": 1,
            "maxLength": 40,
            "default": "PUD"
          }
        },
        "additionalProperties": false
      },
      "ExportIdentityField": {
        "type": "object",
        "description": "A field of POST /exports identity.",
        "required": [
          "name",
          "default",
          "description"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The field, as POST /exports identity takes it.",
            "enum": [
              "well_id",
              "start_date",
              "reserves_category"
            ]
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A value."
            },
            "description": "The words it takes: well_id name, id or uid; start_date til."
          },
          "format": {
            "type": "string",
            "description": "The date form it also takes (start_date).",
            "enum": [
              "YYYY-MM-DD"
            ]
          },
          "type": {
            "type": "string",
            "description": "Its type, for free text (reserves_category).",
            "enum": [
              "string"
            ]
          },
          "max_length": {
            "type": "integer",
            "description": "The most characters it takes.",
            "minimum": 1
          },
          "default": {
            "type": "string",
            "description": "What an export writes when the request leaves it out; with plan, for that plan: well_id is id on a Legacy Forecast."
          },
          "description": {
            "type": "string",
            "description": "What it writes, and the preset option it sets."
          }
        },
        "additionalProperties": false
      },
      "ExportList": {
        "type": "object",
        "description": "Exports.",
        "required": [
          "exports",
          "next_cursor"
        ],
        "properties": {
          "exports": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportJob"
            },
            "description": "Exports, newest first."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Cursor for the next page."
          }
        },
        "additionalProperties": false
      },
      "DeletedExport": {
        "type": "object",
        "description": "Cancelled or removed export.",
        "required": [
          "id",
          "deleted",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Export id.",
            "format": "uuid"
          },
          "deleted": {
            "const": true,
            "description": "Always true."
          },
          "status": {
            "type": "string",
            "description": "Its status when the request came: queued or running, which this call cancelled; or done, error, cancelled or expired, which it removed.",
            "enum": [
              "queued",
              "running",
              "done",
              "error",
              "cancelled",
              "expired"
            ]
          }
        },
        "additionalProperties": false
      },
      "ExportColumn": {
        "type": "object",
        "description": "A column.",
        "required": [
          "name",
          "unit",
          "description",
          "default",
          "stream"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Column name."
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "Unit, as bbl or day."
          },
          "description": {
            "type": "string",
            "description": "What it holds."
          },
          "default": {
            "type": "boolean",
            "description": "Written when the request names no columns."
          },
          "stream": {
            "type": [
              "string",
              "null"
            ],
            "description": "The stream the column belongs to.",
            "enum": [
              "oil",
              "gas",
              "water",
              null
            ]
          }
        },
        "additionalProperties": false
      },
      "ExportOption": {
        "type": "object",
        "description": "A table option.",
        "required": [
          "name",
          "title",
          "type",
          "default",
          "description"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Option name in the table's request object."
          },
          "title": {
            "type": "string",
            "description": "Display name."
          },
          "type": {
            "type": "string",
            "description": "Value type.",
            "enum": [
              "enum",
              "enum[]",
              "boolean",
              "integer",
              "number"
            ]
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A value."
            },
            "description": "Allowed values (enum and enum[])."
          },
          "min": {
            "type": "number",
            "description": "Lowest allowed."
          },
          "max": {
            "type": "number",
            "description": "Highest allowed."
          },
          "default": {
            "anyOf": [
              {
                "type": [
                  "number",
                  "string",
                  "boolean",
                  "null"
                ]
              },
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A value."
                },
                "description": "Values."
              }
            ],
            "description": "Default, for this plan when one is named."
          },
          "description": {
            "type": "string",
            "description": "What it does."
          }
        },
        "additionalProperties": false
      },
      "ExportTableInfo": {
        "type": "object",
        "description": "A table.",
        "required": [
          "id",
          "title",
          "file",
          "description",
          "needs_eur",
          "available",
          "reason",
          "columns",
          "options",
          "rows",
          "parquet"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Table id, as tables[].table takes it.",
            "enum": [
              "monthly",
              "arps",
              "eur",
              "wells",
              "designs",
              "forecast",
              "neighbors",
              "calc_features",
              "subsurface",
              "combocurve_wells",
              "shap",
              "valnav_decline",
              "combocurve_forecast",
              "economics"
            ]
          },
          "title": {
            "type": "string",
            "description": "Display name."
          },
          "file": {
            "type": "string",
            "description": "Its file in the zip."
          },
          "description": {
            "type": "string",
            "description": "What it holds."
          },
          "needs_eur": {
            "type": "boolean",
            "description": "Whether it needs a plan made with eur: true."
          },
          "available": {
            "type": "boolean",
            "description": "Whether it can be exported (from the named plan)."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why not, when it can't."
          },
          "columns": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ExportColumn"
                },
                "description": "Columns."
              },
              {
                "type": "null"
              }
            ],
            "description": "Its columns; null when it writes the plan's own (neighbors, calc features, subsurface), which can't be chosen."
          },
          "options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportOption"
            },
            "description": "Its options."
          },
          "rows": {
            "type": "string",
            "description": "What one row is."
          },
          "parquet": {
            "type": "boolean",
            "description": "Whether an export also writes this table as Parquet, parquet/<id>.parquet with an export_id column, when parquet.available and the request doesn't send parquet: false. A table without it is CSV only."
          },
          "p_levels": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExportTableLevels"
              },
              {
                "type": "null"
              }
            ],
            "description": "Only with include=table_rules: the P-levels this table writes. Null when it writes no P-level rows: p_levels leaves it as it is, and p_levels with no table but these (and no preset aries) is a 400."
          },
          "fixed_columns": {
            "type": "boolean",
            "description": "Only with include=table_rules: true when the table always writes its listed columns, so columns on it is a 400 (valnav_decline, combocurve_wells and combocurve_forecast: their tool's layout; economics: its fixed rollup layout). False on every other table, those whose columns is null included."
          },
          "identity": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "An identity field.",
              "enum": [
                "well_id",
                "start_date",
                "reserves_category"
              ]
            },
            "description": "Only with include=identity: the POST /exports identity fields a tables request with this table may send; empty when it takes none. A request with several tables may send any field one of them lists."
          }
        },
        "additionalProperties": false
      },
      "ExportTableLevels": {
        "type": "object",
        "description": "What a table does with POST /exports p_levels.",
        "required": [
          "available",
          "with_reserves_categories",
          "reason"
        ],
        "properties": {
          "available": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A P-level.",
              "enum": [
                "P50",
                "P10",
                "P90"
              ]
            },
            "description": "The P-levels it writes when p_levels sends them: P50, plus P10 and P90 on a plan made with bands for monthly, eur, arps and combocurve_forecast; P50 alone for valnav_decline.",
            "minItems": 1,
            "maxItems": 200
          },
          "with_reserves_categories": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A P-level.",
              "enum": [
                "P10",
                "P90"
              ]
            },
            "description": "The P-levels it writes only when reserves_categories names a category for each, every level its own: P10 and P90 for valnav_decline on a plan made with bands, else empty. Sent without one, they are a 400."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why it writes none of the plan's other P-levels, when it doesn't: the plan was made without bands."
          }
        },
        "additionalProperties": false
      },
      "ExportPreset": {
        "type": "object",
        "description": "A preset.",
        "required": [
          "id",
          "title",
          "description",
          "tables",
          "available",
          "reason",
          "media_type",
          "contents"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Preset id, as preset takes it."
          },
          "title": {
            "type": "string",
            "description": "Display name."
          },
          "description": {
            "type": "string",
            "description": "What it holds."
          },
          "tables": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportTable"
            },
            "description": "Its tables (for the named plan); empty when unavailable, and for aries, which writes a text file."
          },
          "available": {
            "type": "boolean",
            "description": "Whether it can be exported (from the named plan)."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why not, when it can't."
          },
          "media_type": {
            "type": "string",
            "description": "The Content-Type of its download, GET /exports/{id}/file. application/zip: the preset's files with manifest.json and README.txt; for aries, its text file."
          },
          "contents": {
            "type": "string",
            "description": "What the download holds beside manifest.json and README.txt. tables: a CSV per entry in tables. text: one text file (aries: the ARIES import file, named after the plan), so no columns, streams or Parquet to choose.\n\nWith Parquet, tables also holds parquet/ files for the tables with parquet, and the load/ scripts (load/README.txt and a SQL file per parquet.load_kits entry).",
            "enum": [
              "tables",
              "text"
            ]
          },
          "planned": {
            "type": "boolean",
            "description": "Present, and true, only on a format listed ahead of its build: it can't be requested yet, so available is false, reason says \"Coming soon\" and an export with it answers 400."
          },
          "identity": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "An identity field.",
              "enum": [
                "well_id",
                "start_date",
                "reserves_category"
              ]
            },
            "description": "Only with include=identity: the POST /exports identity fields this preset reads; empty when it reads none. A planned preset lists the fields it will read."
          },
          "note": {
            "type": "string",
            "description": "Only with include=identity, and only when the preset has one: one sentence to show beside the preset, such as a file to load first."
          }
        },
        "additionalProperties": false
      },
      "ExportCategory": {
        "type": "object",
        "description": "A results category and its presets.",
        "required": [
          "id",
          "title",
          "presets"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Category id.",
            "enum": [
              "production",
              "eur",
              "decline",
              "handoff",
              "spacing",
              "drivers",
              "value"
            ]
          },
          "title": {
            "type": "string",
            "description": "Display name."
          },
          "presets": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Preset id."
            },
            "description": "Its preset ids, as preset takes them, the one-click default first."
          }
        },
        "additionalProperties": false
      },
      "ExportGroup": {
        "type": "object",
        "description": "A group of presets to offer.",
        "required": [
          "id",
          "title",
          "presets"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Group id."
          },
          "title": {
            "type": "string",
            "description": "Display name."
          },
          "presets": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Preset id."
            },
            "description": "Its preset ids, as preset takes them, in display order."
          }
        },
        "additionalProperties": false
      },
      "ExportFormats": {
        "type": "object",
        "description": "What exports can hold.",
        "required": [
          "tables",
          "presets",
          "parquet",
          "default_preset",
          "p_levels",
          "aries",
          "limits",
          "callbacks"
        ],
        "properties": {
          "tables": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportTableInfo"
            },
            "description": "Tables."
          },
          "presets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportPreset"
            },
            "description": "Presets."
          },
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportCategory"
            },
            "description": "Only with include=categories: the presets by results category, in display order."
          },
          "groups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExportGroup"
            },
            "description": "Only with include=groups: the presets to offer a person choosing an export, by group, in display order. A preset in no group is still a valid preset. Availability and reasons stay on presets."
          },
          "parquet": {
            "type": "object",
            "description": "Parquet availability.",
            "required": [
              "available",
              "load_kits"
            ],
            "properties": {
              "available": {
                "type": "boolean",
                "description": "Whether Parquet is available."
              },
              "reason": {
                "type": "string",
                "description": "Why Parquet is unavailable."
              },
              "load_kits": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A warehouse id.",
                  "enum": [
                    "snowflake",
                    "databricks"
                  ]
                },
                "description": "The warehouses whose load scripts (load/<id>.sql) an export holds, in zip order, when it writes at least one Parquet table."
              }
            },
            "additionalProperties": false
          },
          "default_preset": {
            "type": "string",
            "description": "The preset an export without preset or tables runs."
          },
          "p_levels": {
            "type": "object",
            "description": "P-levels. P10 is the low curve and P90 the high one, Novi's convention; SPE PRMS uses the reverse (its P90 is the low, proved case).",
            "required": [
              "available",
              "default",
              "reason",
              "convention"
            ],
            "properties": {
              "available": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A P-level.",
                  "enum": [
                    "P50",
                    "P10",
                    "P90"
                  ]
                },
                "description": "The P-levels the plan has: P10 and P90 with bands, else P50.",
                "minItems": 1,
                "maxItems": 200
              },
              "default": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A P-level.",
                  "enum": [
                    "P50",
                    "P10",
                    "P90"
                  ]
                },
                "description": "The P-levels an export writes without p_levels: P50.",
                "minItems": 1,
                "maxItems": 200
              },
              "reason": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Why P10 and P90 aren't available, when they aren't."
              },
              "convention": {
                "type": "string",
                "description": "Which band is the low one."
              }
            },
            "additionalProperties": false
          },
          "aries": {
            "type": "object",
            "description": "ARIES export options.",
            "required": [
              "compat",
              "default_compat"
            ],
            "properties": {
              "compat": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A compat mode.",
                  "enum": [
                    "fixed",
                    "fe"
                  ]
                },
                "description": "The values the aries preset takes in aries.compat: fixed repairs only what Novi's earlier Forecast Engine writes malformed; fe writes its bytes, defects included, and fails where its writer fails."
              },
              "default_compat": {
                "type": "string",
                "description": "The compat mode an aries export without aries.compat writes.",
                "enum": [
                  "fixed",
                  "fe"
                ]
              }
            },
            "additionalProperties": false
          },
          "limits": {
            "type": "object",
            "description": "This server's retention and queue limits.",
            "required": [
              "ttl_hours",
              "max_bytes",
              "max_queued",
              "max_queued_per_plan",
              "max_source_wells",
              "max_source_wells_by_designs",
              "eviction",
              "queue_counts"
            ],
            "properties": {
              "ttl_hours": {
                "type": "number",
                "description": "Hours a done export's file is kept."
              },
              "max_bytes": {
                "type": "integer",
                "description": "Bytes of done files kept; past it the oldest expire first."
              },
              "max_queued": {
                "type": "integer",
                "description": "Exports queued or running at once per model set."
              },
              "max_queued_per_plan": {
                "type": "integer",
                "description": "Exports queued or running at once per plan."
              },
              "max_source_wells": {
                "type": "integer",
                "description": "Forecasts (wells × designs) a wells source may hold."
              },
              "max_source_wells_by_designs": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "description": "The most wells for that many designs.",
                  "minimum": 1
                },
                "description": "For 1 to 10 designs in order, the most wells a wells source may hold with that many designs: max_source_wells divided by the designs, rounded down, at least 1. The server refuses more with 400 on source.wells."
              },
              "eviction": {
                "type": "string",
                "description": "Past max_bytes of finished files, which give up their files first: the oldest done exports; the newest is always kept.",
                "enum": [
                  "oldest_first"
                ]
              },
              "queue_counts": {
                "type": "string",
                "description": "What max_queued and max_queued_per_plan count: exports queued or running.",
                "enum": [
                  "queued_or_running"
                ]
              }
            },
            "additionalProperties": false
          },
          "callbacks": {
            "type": "object",
            "description": "Callbacks on this server.",
            "required": [
              "enabled",
              "hosts",
              "signed",
              "reason",
              "events",
              "signature_header",
              "schemes"
            ],
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Whether callback_url is taken."
              },
              "hosts": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A host, *.suffix for its subdomains, or * for any public host."
                },
                "description": "Hosts callbacks may go to; empty when off."
              },
              "signed": {
                "type": "boolean",
                "description": "Whether deliveries carry X-Export-Signature."
              },
              "reason": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Why callbacks are off, when they are."
              },
              "events": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "An event name.",
                  "enum": [
                    "export.done",
                    "export.failed"
                  ]
                },
                "description": "The event a callback_url can be POSTed, sent as the body's type and the X-Export-Event header; POST /export-callbacks/test sends export.test."
              },
              "signature_header": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The header that carries the delivery's signature when signed is true; null when deliveries aren't signed. Header names are case-insensitive."
              },
              "schemes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A URL scheme, as https."
                },
                "description": "The URL schemes callback_url and POST /export-callbacks/test take. A server that allows private receivers (tests, a LAN) also takes http, though this list still says https."
              }
            },
            "additionalProperties": false
          },
          "identity": {
            "type": "object",
            "description": "Only with include=identity: the identity block POST /exports takes.",
            "required": [
              "fields"
            ],
            "properties": {
              "fields": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ExportIdentityField"
                },
                "description": "The fields POST /exports identity takes: well_id, start_date and reserves_category."
              },
              "unnamed_wells": {
                "type": "integer",
                "description": "Only with plan: how many of its wells well_id name writes as their plan label (Plan well N): no name, or a name equal to that label; with scenario, only that scenario's wells.",
                "minimum": 0
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "CallbackTestRequest": {
        "type": "object",
        "description": "A callback URL.",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "The callback URL to try.",
            "maxLength": 2048
          }
        },
        "additionalProperties": false
      },
      "CallbackTest": {
        "type": "object",
        "description": "One test delivery.",
        "required": [
          "url",
          "ok",
          "status",
          "error",
          "ms"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "The URL tried, as its origin with /… for any path or query."
          },
          "ok": {
            "type": "boolean",
            "description": "Whether the receiver answered 2xx."
          },
          "status": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Its HTTP status; null when none came back."
          },
          "error": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why it failed: the receiver's status, a refused address, a timeout."
          },
          "ms": {
            "type": "integer",
            "description": "How long it took.",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "DeckValue": {
        "type": "object",
        "description": "One deck value.",
        "required": [
          "value",
          "unit",
          "source",
          "note",
          "min",
          "max"
        ],
        "properties": {
          "value": {
            "type": "number",
            "description": "The value."
          },
          "unit": {
            "type": "string",
            "description": "Its unit: $, $/bbl, $/mcf, $/ft, $/lb, bbl/MMcf, fraction or fraction per year."
          },
          "source": {
            "type": "string",
            "description": "assumption: chosen for the deck; fit: from a fitted formula; market: from market data; prototype: a value the deck lacks, from the illustrative Midland deck.",
            "enum": [
              "assumption",
              "fit",
              "market",
              "prototype"
            ]
          },
          "note": {
            "type": "string",
            "description": "Where it comes from."
          },
          "min": {
            "type": "number",
            "description": "The lowest an override may set."
          },
          "max": {
            "type": "number",
            "description": "The highest an override may set."
          }
        },
        "additionalProperties": false
      },
      "EconomicsDeck": {
        "type": "object",
        "description": "The economics deck.",
        "required": [
          "deck_id",
          "version",
          "name",
          "note",
          "tax_note",
          "values",
          "groups",
          "caption",
          "conventions"
        ],
        "properties": {
          "deck_id": {
            "type": "string",
            "description": "The deck's id."
          },
          "version": {
            "type": "integer",
            "description": "Changes whenever a value does.",
            "minimum": 1
          },
          "name": {
            "type": "string",
            "description": "Display name."
          },
          "note": {
            "type": "string",
            "description": "What the deck is."
          },
          "tax_note": {
            "type": "string",
            "description": "The tax regime wording used in the modal."
          },
          "values": {
            "type": "object",
            "description": "Every value, by field.",
            "required": [
              "oil_price",
              "oil_differential",
              "gas_price",
              "gas_differential",
              "ngl_price",
              "ngl_yield_bbl_per_mmcf",
              "shrink",
              "opex_oil",
              "opex_gas",
              "opex_water",
              "royalty",
              "severance_oil",
              "severance_gas",
              "ad_valorem",
              "capex_per_well",
              "capex_drilling_per_ft",
              "capex_stimulation_per_ft",
              "capex_proppant_per_lb",
              "capex_fluid_per_bbl",
              "discount_rate"
            ],
            "properties": {
              "oil_price": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "WTI, flat for the well's life."
              },
              "oil_differential": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Taken off WTI."
              },
              "gas_price": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Henry Hub, flat, no BTU adjustment."
              },
              "gas_differential": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Taken off Henry Hub."
              },
              "ngl_price": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "NGL barrel, flat."
              },
              "ngl_yield_bbl_per_mmcf": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "NGL barrels recovered per MMcf of wellhead gas."
              },
              "shrink": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Share of wellhead gas sold as residue after NGLs come out."
              },
              "opex_oil": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Operating cost per barrel of oil, flat."
              },
              "opex_gas": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Operating cost per mcf of wellhead gas, flat."
              },
              "opex_water": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Water handling per barrel."
              },
              "royalty": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Royalty, a share of revenue."
              },
              "severance_oil": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Severance on oil revenue."
              },
              "severance_gas": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Severance on residue gas and NGL revenue."
              },
              "ad_valorem": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Ad valorem (property) tax, on revenue."
              },
              "capex_per_well": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Fixed capital cost per well."
              },
              "capex_drilling_per_ft": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Drilling per foot of lateral."
              },
              "capex_stimulation_per_ft": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Stimulation per foot of lateral."
              },
              "capex_proppant_per_lb": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Proppant per pound pumped (lb/ft × lateral)."
              },
              "capex_fluid_per_bbl": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "Fluid per barrel pumped (bbl/ft × lateral)."
              },
              "discount_rate": {
                "$ref": "#/components/schemas/DeckValue",
                "description": "The annual rate NPV discounts at."
              }
            },
            "additionalProperties": false
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One group of lines.",
              "required": [
                "title",
                "lines"
              ],
              "properties": {
                "title": {
                  "type": "string",
                  "description": "Group.",
                  "enum": [
                    "Prices",
                    "Costs",
                    "Taxes",
                    "Discounting"
                  ]
                },
                "lines": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "description": "One line."
                  },
                  "description": "Its lines."
                }
              },
              "additionalProperties": false
            },
            "description": "The values as the app's Economics modal lists them."
          },
          "caption": {
            "type": "string",
            "description": "The deck in one line, as the app's Economics line shows it."
          },
          "conventions": {
            "type": "object",
            "description": "How NPV, IRR and payback are counted under each of POST /economics' conventions.",
            "required": [
              "prototype",
              "fe"
            ],
            "properties": {
              "prototype": {
                "type": "string",
                "description": "Yearly discounting, the default: NPV leaves year 1 (months 0 to 12) undiscounted and discounts each later year one more year at the annual rate; payback is in fractional months; IRR is the monthly rate annualized as (1+m)^12 − 1; capex is all at month 0."
              },
              "fe": {
                "type": "string",
                "description": "Monthly discounting. Matches Novi's earlier Forecast Engine: the monthly rate m = (1+r)^(1/12) − 1, the cash flow of month n (0 is capex, 1 the first production month) discounted by (1+m)^n; payback in whole months from turn-on; IRR as under yearly discounting. Capex stays all at month 0, since a scenario has no spud or completion dates."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "EconomicsDeckList": {
        "type": "object",
        "description": "Economics decks.",
        "required": [
          "decks"
        ],
        "properties": {
          "decks": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A deck.",
              "required": [
                "deck_id",
                "version",
                "name",
                "note"
              ],
              "properties": {
                "deck_id": {
                  "type": "string",
                  "description": "The deck's id, as deck_id takes it."
                },
                "version": {
                  "type": "integer",
                  "description": "Its version.",
                  "minimum": 1
                },
                "name": {
                  "type": "string",
                  "description": "Display name."
                },
                "note": {
                  "type": "string",
                  "description": "What the deck is."
                }
              },
              "additionalProperties": false
            },
            "description": "The decks, the default first."
          }
        },
        "additionalProperties": false
      },
      "EconomicsCurve": {
        "type": "object",
        "description": "A cumulative curve, as a forecast stream returns it without `ip_days`.",
        "required": [
          "ip_days",
          "values"
        ],
        "properties": {
          "ip_days": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "Days since first production.",
              "minimum": 1,
              "maximum": 18250
            },
            "description": "ip_days 30, 60, 90 and so on, every 30 days from 30 with none skipped; any other days are a 400 on this field, and oil, gas and water must share them or the well has no cash flow (its `reason` says why). A forecast returns them this way when it is asked for no `ip_days`, and each point is priced as one 30-day month.",
            "minItems": 1,
            "maxItems": 400
          },
          "values": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "Cumulative volume at the matching ip_day."
            },
            "description": "Cumulative volumes, one per ip_day; a null leaves the well without a cash flow."
          }
        },
        "additionalProperties": false
      },
      "EconomicsWell": {
        "type": "object",
        "description": "A well to price.",
        "required": [
          "lateral_ft",
          "design",
          "curves",
          "eur",
          "eur_days"
        ],
        "properties": {
          "label": {
            "type": "string",
            "description": "Names the well in its scenario's reason; else wells[i].",
            "minLength": 1,
            "maxLength": 200
          },
          "lateral_ft": {
            "type": "number",
            "description": "Lateral length, ft.",
            "minimum": 100,
            "maximum": 50000
          },
          "design": {
            "type": "object",
            "description": "The completion design, for capex.",
            "required": [
              "proppant_lb_per_ft",
              "fluid_bbl_per_ft"
            ],
            "properties": {
              "proppant_lb_per_ft": {
                "type": "number",
                "description": "Proppant, lb/ft.",
                "exclusiveMinimum": 0,
                "exclusiveMaximum": 20000
              },
              "fluid_bbl_per_ft": {
                "type": "number",
                "description": "Fluid, bbl/ft.",
                "exclusiveMinimum": 0,
                "exclusiveMaximum": 1000
              }
            },
            "additionalProperties": false
          },
          "curves": {
            "type": "object",
            "description": "The forecast's curves.",
            "required": [
              "oil",
              "gas"
            ],
            "properties": {
              "oil": {
                "$ref": "#/components/schemas/EconomicsCurve"
              },
              "gas": {
                "$ref": "#/components/schemas/EconomicsCurve"
              },
              "water": {
                "$ref": "#/components/schemas/EconomicsCurve",
                "description": "Water, for its opex; without it the well has no cash flow."
              }
            },
            "additionalProperties": false
          },
          "eur": {
            "type": "object",
            "description": "EUR per stream, as a decline fit returned it.",
            "required": [
              "oil",
              "gas"
            ],
            "properties": {
              "oil": {
                "type": "number",
                "description": "Oil EUR, bbl."
              },
              "gas": {
                "type": "number",
                "description": "Gas EUR, mcf."
              }
            },
            "additionalProperties": false
          },
          "eur_days": {
            "type": "number",
            "description": "The EUR's ip_day (oil's `days`): the cash flow runs to it.",
            "minimum": 0,
            "maximum": 21900
          }
        },
        "additionalProperties": false
      },
      "EconomicsRequest": {
        "type": "object",
        "description": "Scenarios, or a forecast, and options.",
        "required": [],
        "properties": {
          "scenarios": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A scenario.",
              "required": [],
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Your id for the scenario, echoed.",
                  "minLength": 1,
                  "maxLength": 200
                },
                "wells": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/EconomicsWell"
                  },
                  "description": "The pad's wells, online together (required unless `plan` is sent).",
                  "minItems": 1,
                  "maxItems": 50
                },
                "plan": {
                  "$ref": "#/components/schemas/EconomicsPlanSource",
                  "description": "Instead of wells: a done plan's wells, by its id, a design and well indexes."
                }
              },
              "additionalProperties": false
            },
            "description": "Scenarios, 1 to 250; required unless `forecast` is sent.",
            "minItems": 1,
            "maxItems": 250
          },
          "forecast": {
            "$ref": "#/components/schemas/EconomicsForecastSource",
            "description": "Instead of scenarios: wells or a layout the server forecasts, one scenario per design. Send scenarios or forecast, not both."
          },
          "deck_id": {
            "type": "string",
            "description": "The deck to price with, one GET /economics/decks lists for the set; left out, the set's default deck (prototype-midland-flat; illustrative-haynesville-gas on a Haynesville set).",
            "enum": [
              "prototype-midland-flat",
              "house-70-3",
              "illustrative-haynesville-gas"
            ]
          },
          "conventions": {
            "type": "string",
            "description": "How NPV and payback are counted: prototype, yearly discounting (the app's default), or fe, monthly discounting, which matches Novi's earlier Forecast Engine.",
            "enum": [
              "prototype",
              "fe"
            ],
            "default": "prototype"
          },
          "deck": {
            "type": "object",
            "description": "Overrides of the deck's values for this request (every deck takes the same ranges); any left out keep the deck's.",
            "required": [],
            "properties": {
              "oil_price": {
                "type": "number",
                "description": "$/bbl; 75 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 300
              },
              "oil_differential": {
                "type": "number",
                "description": "$/bbl; 4 in the illustrative Midland deck.",
                "minimum": -50,
                "maximum": 50
              },
              "gas_price": {
                "type": "number",
                "description": "$/mcf; 3.5 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 50
              },
              "gas_differential": {
                "type": "number",
                "description": "$/mcf; 1 in the illustrative Midland deck.",
                "minimum": -10,
                "maximum": 10
              },
              "ngl_price": {
                "type": "number",
                "description": "$/bbl; 26 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 200
              },
              "ngl_yield_bbl_per_mmcf": {
                "type": "number",
                "description": "bbl/MMcf; 130 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 300
              },
              "shrink": {
                "type": "number",
                "description": "fraction; 0.8 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 1
              },
              "opex_oil": {
                "type": "number",
                "description": "$/bbl; 5.5 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 100
              },
              "opex_gas": {
                "type": "number",
                "description": "$/mcf; 0.5 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 20
              },
              "opex_water": {
                "type": "number",
                "description": "$/bbl; 0.6 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 20
              },
              "royalty": {
                "type": "number",
                "description": "fraction; 0.25 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 0.5
              },
              "severance_oil": {
                "type": "number",
                "description": "fraction; 0.046 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 0.5
              },
              "severance_gas": {
                "type": "number",
                "description": "fraction; 0.075 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 0.5
              },
              "ad_valorem": {
                "type": "number",
                "description": "fraction; 0.025 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 0.2
              },
              "capex_per_well": {
                "type": "number",
                "description": "$; 2500000 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 50000000
              },
              "capex_drilling_per_ft": {
                "type": "number",
                "description": "$/ft; 150 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 2000
              },
              "capex_stimulation_per_ft": {
                "type": "number",
                "description": "$/ft; 125 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 2000
              },
              "capex_proppant_per_lb": {
                "type": "number",
                "description": "$/lb; 0.08 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 2
              },
              "capex_fluid_per_bbl": {
                "type": "number",
                "description": "$/bbl; 3 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 50
              },
              "discount_rate": {
                "type": "number",
                "description": "fraction per year; 0.25 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 1
              }
            },
            "additionalProperties": false
          },
          "include": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "flows: each well's and the pad's monthly cash flows; scenario_flows: each pad's only; totals: sums over the priced scenarios; summary: each scenario's wells, lateral, EUR and completions; breakeven: each scenario's breakeven oil and gas prices.",
              "enum": [
                "flows",
                "scenario_flows",
                "totals",
                "summary",
                "breakeven"
              ]
            },
            "description": "Extras to return. With flows, at most 500 wells across all scenarios (a forecast's wells × designs); 400 above that limit.",
            "maxItems": 5,
            "uniqueItems": true
          }
        },
        "additionalProperties": false
      },
      "EconomicsForecastSource": {
        "type": "object",
        "description": "Wells or a layout to forecast and price: the server runs POST /forecasts' forecast with `eur: true` and the default decline (its run cache answers a repeat), then prices one scenario per design, each well as a plan's well is priced. Use it to price drawn wells under several designs in one call, without sending curves back. Send wells or layout, not both.",
        "required": [
          "designs"
        ],
        "properties": {
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WellInput"
            },
            "description": "Drawn wells, as POST /forecasts takes them, without a `scenario`, `name` or `decline` (each is a 400; required unless `layout` is sent).",
            "minItems": 1,
            "maxItems": 50
          },
          "layout": {
            "$ref": "#/components/schemas/LayoutSource",
            "description": "Instead of wells: a fill boundary the server lays 1 to 50 wells out in, as POST /forecasts takes it."
          },
          "designs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignInput"
            },
            "description": "Completion designs, 1 to 25: each prices every well as one scenario, in this order. Blank values are estimated, as in POST /forecasts.",
            "minItems": 1,
            "maxItems": 25
          },
          "pdp": {
            "type": "boolean",
            "default": true,
            "description": "Space against existing (PDP) wells; false spaces the wells against each other only."
          },
          "til_date": {
            "type": "string",
            "description": "TIL date, YYYY-MM-DD, for every well no narrower layer dates, as POST /forecasts takes it.",
            "format": "date"
          }
        },
        "additionalProperties": false
      },
      "ScenarioSummary": {
        "type": "object",
        "description": "With include summary: the scenario's totals. Wells that couldn't be priced still count in wells, total_lateral_ft and completions.",
        "required": [
          "wells",
          "priced",
          "total_lateral_ft",
          "eur",
          "completions"
        ],
        "properties": {
          "wells": {
            "type": "integer",
            "description": "The scenario's wells.",
            "minimum": 1
          },
          "priced": {
            "type": "integer",
            "description": "Wells with a cash flow.",
            "minimum": 0
          },
          "total_lateral_ft": {
            "type": "number",
            "description": "Lateral summed over every well, ft, rounded to 1 ft."
          },
          "eur": {
            "type": "object",
            "description": "EUR over the wells with an EUR on each of oil and gas the scenario's model set serves (both, on a set serving all three), priced or not.",
            "required": [
              "oil",
              "gas",
              "boe",
              "wells"
            ],
            "properties": {
              "oil": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Oil EUR summed, bbl, to 0.1; null when no well is summed or the set doesn't serve oil."
              },
              "gas": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Gas EUR summed, mcf, to 0.1; null when no well is summed or the set doesn't serve gas."
              },
              "boe": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "oil + gas / 6, BOE, to 0.1, an unserved stream counting 0; null when no well is summed."
              },
              "wells": {
                "type": "integer",
                "description": "The wells summed: those with an EUR on each served stream of oil and gas.",
                "minimum": 0
              }
            },
            "additionalProperties": false
          },
          "completions": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One completion and its wells.",
              "required": [
                "formation",
                "wells",
                "proppant_lb_per_ft",
                "fluid_bbl_per_ft"
              ],
              "properties": {
                "formation": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The wells' formation; null for wells sent in full (raw wells) and wells without one."
                },
                "wells": {
                  "type": "integer",
                  "description": "Wells priced with it.",
                  "minimum": 1
                },
                "proppant_lb_per_ft": {
                  "type": "number",
                  "description": "Proppant, lb/ft."
                },
                "fluid_bbl_per_ft": {
                  "type": "number",
                  "description": "Fluid, bbl/ft."
                }
              },
              "additionalProperties": false
            },
            "description": "Each distinct (formation, proppant, fluid) the wells were priced with, by formation (null last), then proppant, then fluid."
          }
        },
        "additionalProperties": false
      },
      "EconomicsPlanSource": {
        "type": "object",
        "description": "A done plan's wells to price by reference instead of their curves: one design, every well (up to 50) or the listed indexes. The plan must be done and made with `eur: true` (409 otherwise).\n\nEach well is priced as the plan forecast it: lateral from its ends, its formation's completions under the design, its curves and EUR. A well whose forecast or EUR failed leaves the scenario unpriced, with a reason naming it Plan well N.",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "A done plan's id, from POST /plans.",
            "format": "uuid"
          },
          "design": {
            "type": "integer",
            "description": "The plan design whose forecasts and completions are priced, its index from 0.",
            "minimum": 0,
            "maximum": 9,
            "default": 0
          },
          "wells": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "A plan well index from 0.",
              "minimum": 0
            },
            "description": "The plan wells to price, by index; absent prices every well of a plan of up to 50.",
            "minItems": 1,
            "maxItems": 50,
            "uniqueItems": true
          },
          "scenario": {
            "type": "string",
            "description": "On a plan made with scenarios: price this scenario's wells (up to 50, else send wells). A scenario prices one development, so on such a plan send scenario or wells all in one scenario (400 otherwise); on a plan without scenarios it is a 400.",
            "minLength": 1,
            "maxLength": 60
          }
        },
        "additionalProperties": false
      },
      "ScenarioEconomics": {
        "type": "object",
        "description": "One scenario's economics.",
        "required": [
          "economics",
          "reason",
          "wells"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "The scenario's key, when it sent one."
          },
          "forecast": {
            "type": "object",
            "description": "With forecast: the design this scenario priced.",
            "required": [
              "design"
            ],
            "properties": {
              "design": {
                "type": "integer",
                "description": "The design priced: its index in the response's forecast.designs.",
                "minimum": 0
              }
            },
            "additionalProperties": false
          },
          "plan": {
            "type": "object",
            "description": "The plan reference the scenario was priced from.",
            "required": [
              "id",
              "design",
              "wells"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Plan id.",
                "format": "uuid"
              },
              "design": {
                "type": "integer",
                "description": "The design priced."
              },
              "wells": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "description": "A plan well index."
                },
                "description": "The plan wells priced, in order."
              },
              "scenario": {
                "type": "string",
                "description": "On a plan made with scenarios, the scenario priced."
              }
            },
            "additionalProperties": false
          },
          "economics": {
            "type": [
              "object",
              "null"
            ],
            "description": "The pad's economics, or null.",
            "required": [
              "capex",
              "irr_pct",
              "payback_months",
              "npv"
            ],
            "properties": {
              "capex": {
                "type": "number",
                "description": "Capex, $, all at month 0."
              },
              "irr_pct": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "IRR, % a year, annualized from the monthly rate (capped at 100% a month); null when the flows never return their capex."
              },
              "payback_months": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Months until the running total turns non-negative: interpolated within the month, or whole months under fe; null when it never does."
              },
              "npv": {
                "type": "number",
                "description": "NPV, $, at the effective deck discount_rate, discounted as conventions says."
              }
            },
            "additionalProperties": false
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why economics is null: the first well without a cash flow and why, or the pad's."
          },
          "wells": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One well.",
              "required": [
                "reason"
              ],
              "properties": {
                "reason": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Why the well has no cash flow, or null."
                },
                "flows": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "number",
                    "description": "$ in a month."
                  },
                  "description": "With include flows: its monthly cash flow, month 0 the capex, or null."
                }
              },
              "additionalProperties": false
            },
            "description": "Each well, in request order."
          },
          "flows": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "number",
              "description": "$ in a month."
            },
            "description": "With include flows or scenario_flows: the pad's monthly cash flow, or null without one."
          },
          "summary": {
            "$ref": "#/components/schemas/ScenarioSummary"
          },
          "breakeven": {
            "type": [
              "object",
              "null"
            ],
            "description": "With include breakeven: the prices at which this scenario's npv is 0, every other deck value and override held, under the request's conventions; null when economics is null.",
            "required": [
              "oil_price",
              "gas_price",
              "discount_rate"
            ],
            "properties": {
              "oil_price": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "WTI, $/bbl: the flat oil price at which npv is 0, to within $0.000001; null when npv doesn't cross 0 between oil_price's min and max (GET /economics/deck)."
              },
              "gas_price": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Henry Hub, $/mcf: the flat gas price at which npv is 0, to within $0.000001; null when npv doesn't cross 0 between gas_price's min and max."
              },
              "discount_rate": {
                "type": "number",
                "description": "The effective annual discount rate npv was taken at, as deck.discount_rate."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "EconomicsResponse": {
        "type": "object",
        "description": "Economics per scenario.",
        "required": [
          "deck",
          "conventions",
          "scenarios"
        ],
        "properties": {
          "deck": {
            "type": "object",
            "description": "The effective deck.",
            "required": [
              "deck_id",
              "version",
              "name",
              "overrides",
              "discount_rate",
              "values"
            ],
            "properties": {
              "deck_id": {
                "type": "string",
                "description": "The deck's id."
              },
              "version": {
                "type": "integer",
                "description": "Its version.",
                "minimum": 1
              },
              "name": {
                "type": "string",
                "description": "Its display name, as GET /economics/decks lists it; name results by it."
              },
              "overrides": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A field.",
                  "enum": [
                    "oil_price",
                    "oil_differential",
                    "gas_price",
                    "gas_differential",
                    "ngl_price",
                    "ngl_yield_bbl_per_mmcf",
                    "shrink",
                    "opex_oil",
                    "opex_gas",
                    "opex_water",
                    "royalty",
                    "severance_oil",
                    "severance_gas",
                    "ad_valorem",
                    "capex_per_well",
                    "capex_drilling_per_ft",
                    "capex_stimulation_per_ft",
                    "capex_proppant_per_lb",
                    "capex_fluid_per_bbl",
                    "discount_rate"
                  ]
                },
                "description": "The fields this request overrode."
              },
              "discount_rate": {
                "type": "number",
                "description": "The effective annual discount rate used for npv."
              },
              "values": {
                "type": "object",
                "description": "The values priced with.",
                "required": [
                  "oil_price",
                  "oil_differential",
                  "gas_price",
                  "gas_differential",
                  "ngl_price",
                  "ngl_yield_bbl_per_mmcf",
                  "shrink",
                  "opex_oil",
                  "opex_gas",
                  "opex_water",
                  "royalty",
                  "severance_oil",
                  "severance_gas",
                  "ad_valorem",
                  "capex_per_well",
                  "capex_drilling_per_ft",
                  "capex_stimulation_per_ft",
                  "capex_proppant_per_lb",
                  "capex_fluid_per_bbl",
                  "discount_rate"
                ],
                "properties": {
                  "oil_price": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "oil_differential": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "gas_price": {
                    "type": "number",
                    "description": "$/mcf"
                  },
                  "gas_differential": {
                    "type": "number",
                    "description": "$/mcf"
                  },
                  "ngl_price": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "ngl_yield_bbl_per_mmcf": {
                    "type": "number",
                    "description": "bbl/MMcf"
                  },
                  "shrink": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "opex_oil": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "opex_gas": {
                    "type": "number",
                    "description": "$/mcf"
                  },
                  "opex_water": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "royalty": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "severance_oil": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "severance_gas": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "ad_valorem": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "capex_per_well": {
                    "type": "number",
                    "description": "$"
                  },
                  "capex_drilling_per_ft": {
                    "type": "number",
                    "description": "$/ft"
                  },
                  "capex_stimulation_per_ft": {
                    "type": "number",
                    "description": "$/ft"
                  },
                  "capex_proppant_per_lb": {
                    "type": "number",
                    "description": "$/lb"
                  },
                  "capex_fluid_per_bbl": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "discount_rate": {
                    "type": "number",
                    "description": "fraction per year"
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "conventions": {
            "type": "string",
            "description": "The conventions priced under.",
            "enum": [
              "prototype",
              "fe"
            ]
          },
          "forecast": {
            "type": "object",
            "description": "With forecast: what was forecast; layout only when one was sent.",
            "required": [
              "pdp",
              "wells",
              "designs"
            ],
            "properties": {
              "pdp": {
                "type": "boolean",
                "description": "Whether the wells spaced against existing wells."
              },
              "wells": {
                "type": "integer",
                "description": "Wells forecast.",
                "minimum": 1
              },
              "designs": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Design"
                },
                "description": "The designs as run, one scenario each, in order."
              },
              "layout": {
                "$ref": "#/components/schemas/LayoutEcho"
              }
            },
            "additionalProperties": false
          },
          "scenarios": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScenarioEconomics"
            },
            "description": "One per scenario, in request order (with forecast, one per design)."
          },
          "totals": {
            "$ref": "#/components/schemas/EconomicsTotals",
            "description": "With include totals: sums over the priced scenarios."
          }
        },
        "additionalProperties": false
      },
      "EconomicsTotals": {
        "type": "object",
        "description": "Sums over the priced scenarios. IRR and payback don't add, so there are none: price the batches as one scenario for those.",
        "required": [
          "scenarios",
          "priced",
          "wells",
          "npv",
          "capex"
        ],
        "properties": {
          "scenarios": {
            "type": "integer",
            "description": "Scenarios in the request.",
            "minimum": 1
          },
          "priced": {
            "type": "integer",
            "description": "Scenarios with economics.",
            "minimum": 0
          },
          "wells": {
            "type": "integer",
            "description": "Wells in the priced scenarios.",
            "minimum": 0
          },
          "npv": {
            "type": [
              "number",
              "null"
            ],
            "description": "NPV summed over the priced scenarios, $; null when none is priced."
          },
          "capex": {
            "type": [
              "number",
              "null"
            ],
            "description": "Capex summed over the priced scenarios, $; null when none is priced."
          },
          "flows": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "number",
              "description": "$ in a month."
            },
            "description": "With include flows or scenario_flows: the priced scenarios' monthly cash flows summed month by month from month 0, all online together; null when none is priced."
          }
        },
        "additionalProperties": false
      },
      "PlanEconomicsRequest": {
        "type": "object",
        "description": "A plan priced in the background. Every field is optional.",
        "required": [],
        "properties": {
          "design": {
            "type": "integer",
            "description": "The plan design priced, its index from 0.",
            "minimum": 0,
            "maximum": 9,
            "default": 0
          },
          "scenario": {
            "type": "string",
            "description": "On a plan made with scenarios, the one to price: required there (a 400 lists them), and a 400 on a plan without scenarios. A job prices one development; price each scenario in its own job.",
            "minLength": 1,
            "maxLength": 60
          },
          "deck_id": {
            "type": "string",
            "description": "The deck to price with, one GET /economics/decks lists for the set; left out, the set's default deck (prototype-midland-flat; illustrative-haynesville-gas on a Haynesville set).",
            "enum": [
              "prototype-midland-flat",
              "house-70-3",
              "illustrative-haynesville-gas"
            ]
          },
          "deck": {
            "type": "object",
            "description": "Overrides of the deck's values for this request (every deck takes the same ranges); any left out keep the deck's.",
            "required": [],
            "properties": {
              "oil_price": {
                "type": "number",
                "description": "$/bbl; 75 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 300
              },
              "oil_differential": {
                "type": "number",
                "description": "$/bbl; 4 in the illustrative Midland deck.",
                "minimum": -50,
                "maximum": 50
              },
              "gas_price": {
                "type": "number",
                "description": "$/mcf; 3.5 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 50
              },
              "gas_differential": {
                "type": "number",
                "description": "$/mcf; 1 in the illustrative Midland deck.",
                "minimum": -10,
                "maximum": 10
              },
              "ngl_price": {
                "type": "number",
                "description": "$/bbl; 26 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 200
              },
              "ngl_yield_bbl_per_mmcf": {
                "type": "number",
                "description": "bbl/MMcf; 130 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 300
              },
              "shrink": {
                "type": "number",
                "description": "fraction; 0.8 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 1
              },
              "opex_oil": {
                "type": "number",
                "description": "$/bbl; 5.5 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 100
              },
              "opex_gas": {
                "type": "number",
                "description": "$/mcf; 0.5 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 20
              },
              "opex_water": {
                "type": "number",
                "description": "$/bbl; 0.6 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 20
              },
              "royalty": {
                "type": "number",
                "description": "fraction; 0.25 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 0.5
              },
              "severance_oil": {
                "type": "number",
                "description": "fraction; 0.046 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 0.5
              },
              "severance_gas": {
                "type": "number",
                "description": "fraction; 0.075 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 0.5
              },
              "ad_valorem": {
                "type": "number",
                "description": "fraction; 0.025 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 0.2
              },
              "capex_per_well": {
                "type": "number",
                "description": "$; 2500000 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 50000000
              },
              "capex_drilling_per_ft": {
                "type": "number",
                "description": "$/ft; 150 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 2000
              },
              "capex_stimulation_per_ft": {
                "type": "number",
                "description": "$/ft; 125 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 2000
              },
              "capex_proppant_per_lb": {
                "type": "number",
                "description": "$/lb; 0.08 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 2
              },
              "capex_fluid_per_bbl": {
                "type": "number",
                "description": "$/bbl; 3 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 50
              },
              "discount_rate": {
                "type": "number",
                "description": "fraction per year; 0.25 in the illustrative Midland deck.",
                "minimum": 0,
                "maximum": 1
              }
            },
            "additionalProperties": false
          },
          "conventions": {
            "type": "string",
            "description": "How NPV and payback are counted: prototype, yearly discounting (the app's default), or fe, monthly discounting, which matches Novi's earlier Forecast Engine.",
            "enum": [
              "prototype",
              "fe"
            ],
            "default": "prototype"
          },
          "group_by": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "pad: each pad key, in plan order of its first well, no pad last; formation: each landing zone, in GET /formations order, none last.",
              "enum": [
                "pad",
                "formation"
              ]
            },
            "description": "Groups to sum, each once. Absent: totals only.",
            "uniqueItems": true
          },
          "include": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "wells: one row per well, in plan order; breakeven: flat oil and gas breakeven prices on the totals and each group.",
              "enum": [
                "wells",
                "breakeven"
              ]
            },
            "description": "Optional parts, each once.",
            "uniqueItems": true
          }
        },
        "additionalProperties": false
      },
      "EconomicsRollup": {
        "type": "object",
        "description": "The priced wells of a plan, a pad or a landing zone, summed month by month as if all came online together.",
        "required": [
          "wells",
          "priced",
          "capex",
          "npv",
          "irr_pct",
          "payback_months",
          "reason"
        ],
        "properties": {
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "On a group: the pad key or formation; null for the wells without one. Absent on totals."
          },
          "name": {
            "type": "string",
            "description": "On a pad group, the pad's name when the plan gives one in `pads[].name`; absent otherwise, and on totals and formation groups. `key` stays the pad key."
          },
          "wells": {
            "type": "integer",
            "description": "Wells in it.",
            "minimum": 0
          },
          "priced": {
            "type": "integer",
            "description": "Wells with a cash flow, summed.",
            "minimum": 0
          },
          "capex": {
            "type": [
              "number",
              "null"
            ],
            "description": "Capex of the priced wells, $, all at month 0; null when none is priced."
          },
          "npv": {
            "type": [
              "number",
              "null"
            ],
            "description": "NPV of the summed cash flow, $, at the deck discount_rate, as conventions says; null when none is priced."
          },
          "irr_pct": {
            "type": [
              "number",
              "null"
            ],
            "description": "IRR of the summed cash flow, % a year; null when it never returns its capex or none is priced."
          },
          "payback_months": {
            "type": [
              "number",
              "null"
            ],
            "description": "Payback of the summed cash flow, months; null when it never pays back or none is priced."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "The first unpriced well (by plan index) and why, as POST /economics names it; null when every well is priced."
          },
          "breakeven": {
            "type": [
              "object",
              "null"
            ],
            "description": "With include breakeven: the flat oil and gas prices at which npv is 0, over the priced wells; null when none is priced.",
            "required": [
              "oil_price",
              "gas_price",
              "discount_rate"
            ],
            "properties": {
              "oil_price": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "WTI, $/bbl: the flat oil price at which npv is 0, to within $0.000001; null when npv doesn't cross 0 between oil_price's min and max (GET /economics/deck)."
              },
              "gas_price": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Henry Hub, $/mcf: the flat gas price at which npv is 0, to within $0.000001; null when npv doesn't cross 0 between gas_price's min and max."
              },
              "discount_rate": {
                "type": "number",
                "description": "The effective annual discount rate npv was taken at, as deck.discount_rate."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "PlanEconomicsWell": {
        "type": "object",
        "description": "One well priced alone.",
        "required": [
          "index",
          "label",
          "pad",
          "formation",
          "capex",
          "npv",
          "irr_pct",
          "payback_months",
          "reason"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "The well's plan index.",
            "minimum": 0
          },
          "label": {
            "type": "string",
            "description": "The well's name, else Plan well N."
          },
          "pad": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its pad key; null without one."
          },
          "pad_name": {
            "type": "string",
            "description": "The pad's name when the plan gives one in `pads[].name`; absent otherwise. `pad` stays the key."
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its target formation; null without one."
          },
          "capex": {
            "type": [
              "number",
              "null"
            ],
            "description": "Capex, $; null when unpriced."
          },
          "npv": {
            "type": [
              "number",
              "null"
            ],
            "description": "NPV, $; null when unpriced."
          },
          "irr_pct": {
            "type": [
              "number",
              "null"
            ],
            "description": "IRR, % a year; null when unpriced or it never returns its capex."
          },
          "payback_months": {
            "type": [
              "number",
              "null"
            ],
            "description": "Payback, months; null when unpriced or it never pays back."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why it has no cash flow, or null."
          }
        },
        "additionalProperties": false
      },
      "PlanEconomics": {
        "type": "object",
        "description": "A plan priced; numbers unrounded, as POST /economics answers them.",
        "required": [
          "plan_id",
          "design",
          "scenario",
          "deck",
          "conventions",
          "totals"
        ],
        "properties": {
          "plan_id": {
            "type": "string",
            "description": "The plan.",
            "format": "uuid"
          },
          "design": {
            "type": "integer",
            "description": "The design priced.",
            "minimum": 0
          },
          "scenario": {
            "type": [
              "string",
              "null"
            ],
            "description": "The scenario priced; null on a plan without scenarios."
          },
          "deck": {
            "type": "object",
            "description": "The effective deck.",
            "required": [
              "deck_id",
              "version",
              "name",
              "overrides",
              "discount_rate",
              "values"
            ],
            "properties": {
              "deck_id": {
                "type": "string",
                "description": "The deck's id."
              },
              "version": {
                "type": "integer",
                "description": "Its version.",
                "minimum": 1
              },
              "name": {
                "type": "string",
                "description": "Its display name, as GET /economics/decks lists it; name results by it."
              },
              "overrides": {
                "type": "array",
                "items": {
                  "type": "string",
                  "description": "A field.",
                  "enum": [
                    "oil_price",
                    "oil_differential",
                    "gas_price",
                    "gas_differential",
                    "ngl_price",
                    "ngl_yield_bbl_per_mmcf",
                    "shrink",
                    "opex_oil",
                    "opex_gas",
                    "opex_water",
                    "royalty",
                    "severance_oil",
                    "severance_gas",
                    "ad_valorem",
                    "capex_per_well",
                    "capex_drilling_per_ft",
                    "capex_stimulation_per_ft",
                    "capex_proppant_per_lb",
                    "capex_fluid_per_bbl",
                    "discount_rate"
                  ]
                },
                "description": "The fields this request overrode."
              },
              "discount_rate": {
                "type": "number",
                "description": "The effective annual discount rate used for npv."
              },
              "values": {
                "type": "object",
                "description": "The values priced with.",
                "required": [
                  "oil_price",
                  "oil_differential",
                  "gas_price",
                  "gas_differential",
                  "ngl_price",
                  "ngl_yield_bbl_per_mmcf",
                  "shrink",
                  "opex_oil",
                  "opex_gas",
                  "opex_water",
                  "royalty",
                  "severance_oil",
                  "severance_gas",
                  "ad_valorem",
                  "capex_per_well",
                  "capex_drilling_per_ft",
                  "capex_stimulation_per_ft",
                  "capex_proppant_per_lb",
                  "capex_fluid_per_bbl",
                  "discount_rate"
                ],
                "properties": {
                  "oil_price": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "oil_differential": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "gas_price": {
                    "type": "number",
                    "description": "$/mcf"
                  },
                  "gas_differential": {
                    "type": "number",
                    "description": "$/mcf"
                  },
                  "ngl_price": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "ngl_yield_bbl_per_mmcf": {
                    "type": "number",
                    "description": "bbl/MMcf"
                  },
                  "shrink": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "opex_oil": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "opex_gas": {
                    "type": "number",
                    "description": "$/mcf"
                  },
                  "opex_water": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "royalty": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "severance_oil": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "severance_gas": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "ad_valorem": {
                    "type": "number",
                    "description": "fraction"
                  },
                  "capex_per_well": {
                    "type": "number",
                    "description": "$"
                  },
                  "capex_drilling_per_ft": {
                    "type": "number",
                    "description": "$/ft"
                  },
                  "capex_stimulation_per_ft": {
                    "type": "number",
                    "description": "$/ft"
                  },
                  "capex_proppant_per_lb": {
                    "type": "number",
                    "description": "$/lb"
                  },
                  "capex_fluid_per_bbl": {
                    "type": "number",
                    "description": "$/bbl"
                  },
                  "discount_rate": {
                    "type": "number",
                    "description": "fraction per year"
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "conventions": {
            "type": "string",
            "description": "The conventions priced under.",
            "enum": [
              "prototype",
              "fe"
            ]
          },
          "totals": {
            "$ref": "#/components/schemas/EconomicsRollup"
          },
          "groups": {
            "type": "object",
            "description": "With group_by: the groups asked for.",
            "required": [],
            "properties": {
              "pad": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/EconomicsRollup"
                },
                "description": "With group_by pad: each pad key in plan order of its first well, no pad last; never folded."
              },
              "formation": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/EconomicsRollup"
                },
                "description": "With group_by formation: each formation in GET /formations order, none last."
              }
            },
            "additionalProperties": false
          },
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanEconomicsWell"
            },
            "description": "With include wells: every well priced, in plan order."
          }
        },
        "additionalProperties": false
      },
      "PlanEconomicsJob": {
        "type": "object",
        "description": "A plan economics job.",
        "required": [
          "id",
          "plan_id",
          "status",
          "created_at",
          "finished_at",
          "seconds",
          "result",
          "error",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Job id.",
            "format": "uuid"
          },
          "plan_id": {
            "type": "string",
            "description": "The plan priced.",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "description": "running, then done or error.",
            "enum": [
              "running",
              "done",
              "error"
            ]
          },
          "created_at": {
            "type": "string",
            "description": "When it was requested.",
            "format": "date-time"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "When it finished or failed.",
            "format": "date-time"
          },
          "seconds": {
            "type": "number",
            "description": "Run time so far, or in total once finished."
          },
          "result": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PlanEconomics"
              },
              {
                "type": "null"
              }
            ],
            "description": "Once done, the plan priced; null otherwise."
          },
          "error": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ErrorBody"
              },
              {
                "type": "null"
              }
            ],
            "description": "Once failed, why; null otherwise."
          },
          "links": {
            "type": "object",
            "description": "Related URLs.",
            "required": [
              "self"
            ],
            "properties": {
              "self": {
                "type": "string",
                "description": "This job."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "AreasRequest": {
        "type": "object",
        "description": "Send exactly one of shapefile, geojson, kml or kmz.",
        "required": [],
        "properties": {
          "shapefile": {
            "type": "string",
            "description": "A zipped shapefile (.shp, .dbf and .prj; .cpg and .shx optional) in base64: RFC 4648, padded, with no line breaks or data: prefix. Where you can, upload the file itself as multipart/form-data instead.",
            "contentEncoding": "base64",
            "contentMediaType": "application/zip"
          },
          "geojson": {
            "type": "object",
            "description": "A GeoJSON FeatureCollection, Feature, Polygon or MultiPolygon. Coordinates in degrees are WGS 84 (RFC 7946); others need a crs member or crs, or are detected."
          },
          "kml": {
            "type": "string",
            "description": "A KML file's text (OGC KML 2.2, UTF-8): Placemark polygons in WGS 84."
          },
          "kmz": {
            "type": "string",
            "description": "A KMZ (a zip holding a .kml) in base64: RFC 4648, padded, with no line breaks or data: prefix. Where you can, upload the file itself as multipart/form-data instead.",
            "contentEncoding": "base64",
            "contentMediaType": "application/vnd.google-earth.kmz"
          },
          "crs": {
            "type": [
              "string",
              "integer",
              "null"
            ],
            "description": "The file's coordinate system as an EPSG code (EPSG:2277, epsg:2277 or 2277), overriding the file's own and detection.\n\nOne of EPSG:2275, EPSG:2276, EPSG:2277, EPSG:2278, EPSG:2279, EPSG:2257, EPSG:2258, EPSG:2259, EPSG:32137, EPSG:32138, EPSG:32139, EPSG:32140, EPSG:32141, EPSG:32112, EPSG:32113, EPSG:32114, EPSG:6578, EPSG:6588, EPSG:3081, EPSG:3082, EPSG:3083, EPSG:5070, EPSG:3857, EPSG:26913, EPSG:26914, EPSG:32613, EPSG:32614, EPSG:4326, EPSG:4269, EPSG:32037, EPSG:32038, EPSG:32039, EPSG:32040, EPSG:32041, EPSG:32012, EPSG:32013, EPSG:32014, EPSG:26713, EPSG:26714, EPSG:4267."
          },
          "name_field": {
            "type": [
              "string",
              "null"
            ],
            "description": "The field (any case) whose value names each area, read even past the property caps; 400 with details.fields when the file has no such field. Blank picks one.",
            "maxLength": 100
          },
          "name_fields": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "description": "A field name.",
              "minLength": 1,
              "maxLength": 100
            },
            "minItems": 1,
            "maxItems": 5,
            "description": "Fields (any case) whose values, in this order with blanks left out, name each area, joined by name_separator; each read even past the property caps. 400 on name_fields[i] for a field the file lacks (with details.fields) or one that repeats an earlier field; 400 on name_fields with name_field."
          },
          "name_separator": {
            "type": [
              "string",
              "null"
            ],
            "description": "What joins the name_fields values, used as sent: 0 to 8 characters, one space when absent; only with name_fields.",
            "maxLength": 8
          }
        },
        "additionalProperties": false
      },
      "AreasUpload": {
        "type": "object",
        "description": "A multipart/form-data upload: one file part and optional text parts; any other part, or a second file, is a 400.",
        "required": [
          "file"
        ],
        "properties": {
          "file": {
            "type": "string",
            "description": "The zipped shapefile (.zip), GeoJSON, KML or KMZ file, as a file part; GeoJSON may also come as a text part (curl -F file=<units.geojson). A zip is told by its first bytes (PK\\x03\\x04); one holding a .kml and no .shp is a KMZ. A first character < after a BOM and whitespace is KML.",
            "format": "binary"
          },
          "crs": {
            "type": "string",
            "description": "As crs in the JSON body: an EPSG code, as EPSG:2277 or 2277."
          },
          "name_field": {
            "type": "string",
            "description": "As name_field in the JSON body."
          },
          "name_fields": {
            "type": "string",
            "description": "As name_fields in the JSON body, as JSON text: [\"name\", \"lease_no\"]."
          },
          "name_separator": {
            "type": "string",
            "description": "As name_separator in the JSON body: the part's text as sent."
          }
        },
        "additionalProperties": false
      },
      "AreaCrs": {
        "type": "object",
        "description": "The coordinate system the file was read in, and how sure that is.",
        "required": [
          "code",
          "name",
          "source",
          "datum_shift",
          "max_offset_ft",
          "alternatives"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "The system read: an EPSG code, as EPSG:2277, or the .prj's name when no supported system matches it (it was read through the .prj itself)."
          },
          "name": {
            "type": "string",
            "description": "Its name, as NAD83 / Texas Central (ftUS)."
          },
          "source": {
            "type": "string",
            "description": "request: the request's crs; file: the .prj, the GeoJSON (crs member, or degrees per RFC 7946) or a KML (WGS 84); detected: the first supported system that puts the areas on the dataset.",
            "enum": [
              "request",
              "file",
              "detected"
            ]
          },
          "datum_shift": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "nadcon_conus",
              null
            ],
            "description": "nadcon_conus: NAD27, shifted to NAD83 with NOAA's NADCON conus grid; else null."
          },
          "max_offset_ft": {
            "type": "integer",
            "description": "The largest alternative's offset_ft, or 0: how far the areas could be off if the file is in another system that also fits.",
            "minimum": 0
          },
          "alternatives": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "Another system the coordinates could be in: one that also puts the areas on the dataset, or NAD27 when nothing does and they are degrees.",
              "required": [
                "code",
                "name",
                "offset_ft"
              ],
              "properties": {
                "code": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Its EPSG code; null for an international-foot variant, which crs can't name."
                },
                "name": {
                  "type": "string",
                  "description": "Its name."
                },
                "offset_ft": {
                  "type": "integer",
                  "description": "The farthest a sampled vertex lands from where it is read now, ft.",
                  "minimum": 1
                }
              },
              "additionalProperties": false
            },
            "description": "With detection: the other systems that fit, in preference order, under 1 ft apart listed once."
          }
        },
        "additionalProperties": false
      },
      "AreaGeometry": {
        "description": "The area in WGS 84 (RFC 7946): rings closed (the last point repeats the first), outer rings counterclockwise and holes clockwise, coordinates at 1e-7°.",
        "oneOf": [
          {
            "type": "object",
            "description": "A polygon.",
            "required": [
              "type",
              "coordinates"
            ],
            "properties": {
              "type": {
                "const": "Polygon",
                "description": "One part."
              },
              "coordinates": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/LngLat"
                  },
                  "description": "A ring.",
                  "minItems": 4
                },
                "description": "The outer ring, then its holes."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "A multipolygon.",
            "required": [
              "type",
              "coordinates"
            ],
            "properties": {
              "type": {
                "const": "MultiPolygon",
                "description": "Several parts."
              },
              "coordinates": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/LngLat"
                    },
                    "description": "A ring.",
                    "minItems": 4
                  },
                  "description": "A part: its outer ring, then its holes."
                },
                "description": "The parts."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "AreaFill": {
        "type": "object",
        "description": "A ring POST /layouts/fill takes.",
        "required": [
          "polygon",
          "simplified_from",
          "max_deviation_ft",
          "dropped_parts",
          "dropped_holes"
        ],
        "properties": {
          "polygon": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LngLat"
            },
            "description": "The largest part's outer ring, open (no closing point), at most 500 corners: send it as polygon to POST /layouts/fill, or in a layout. A layout from it alone ignores the area's other parts and its holes; to fill every part and leave the holes out, send the area's geometry as area instead.",
            "minItems": 3,
            "maxItems": 500
          },
          "simplified_from": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The ring's corners before simplifying, or null when it was not simplified."
          },
          "max_deviation_ft": {
            "type": "number",
            "description": "The farthest a corner dropped in simplifying lies from the edge that replaced it, ft; 0 when none was.",
            "minimum": 0
          },
          "dropped_parts": {
            "type": "integer",
            "description": "Parts of the area the ring leaves out.",
            "minimum": 0
          },
          "dropped_holes": {
            "type": "integer",
            "description": "Holes in its part the ring leaves out.",
            "minimum": 0
          }
        },
        "additionalProperties": false
      },
      "Area": {
        "type": "object",
        "description": "An area.",
        "required": [
          "id",
          "name",
          "properties",
          "geometry",
          "acres",
          "long_axis_azimuth_deg",
          "parts",
          "holes",
          "vertices",
          "in_dataset",
          "fill"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Its record (shapefile) or feature (GeoJSON) index in the file, from 0.",
            "minimum": 0
          },
          "name": {
            "type": "string",
            "description": "From the name field or fields, else Area <id + 1>."
          },
          "properties": {
            "type": "object",
            "additionalProperties": {
              "type": [
                "number",
                "string",
                "boolean",
                "null"
              ]
            },
            "description": "The file's attributes: numbers, text (cut at 200 characters), booleans, dates (YYYY-MM-DD) and nulls, at most 50, plus the asked name fields."
          },
          "geometry": {
            "$ref": "#/components/schemas/AreaGeometry"
          },
          "acres": {
            "type": "number",
            "description": "Area, acres, holes taken out."
          },
          "long_axis_azimuth_deg": {
            "type": "integer",
            "description": "The bearing of the largest part's longest edge, degrees from north, -90 to 90: an azimuth_deg for POST /layouts/fill.",
            "minimum": -90,
            "maximum": 90
          },
          "parts": {
            "type": "integer",
            "description": "Parts (outer rings).",
            "minimum": 1
          },
          "holes": {
            "type": "integer",
            "description": "Holes in all parts.",
            "minimum": 0
          },
          "vertices": {
            "type": "integer",
            "description": "Corners in all rings, closing points not counted.",
            "minimum": 3
          },
          "in_dataset": {
            "type": "boolean",
            "description": "True when the area's bbox meets the dataset's (GET /dataset bbox); a warning counts the areas where it is false."
          },
          "fill": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/AreaFill"
              },
              {
                "type": "null"
              }
            ],
            "description": "The ring to fill with wells, or null when the simplified ring's edges cross, or it has fewer than 3 corners or no area."
          }
        },
        "additionalProperties": false
      },
      "AreasResponse": {
        "type": "object",
        "description": "Areas read from a file.",
        "required": [
          "count",
          "name_field",
          "fields",
          "crs",
          "areas",
          "skipped",
          "warnings"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "Areas read.",
            "minimum": 1
          },
          "name_field": {
            "type": [
              "string",
              "null"
            ],
            "description": "The field the names came from, or null."
          },
          "name_fields": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A field, as the file spells it."
            },
            "description": "Only when the request sent name_fields: those fields as the file spells them, in the order sent; name_field is the first."
          },
          "name_separator": {
            "type": "string",
            "description": "Only when the request sent name_fields: what joined their values."
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A field name."
            },
            "description": "The attributes the areas carry, in file order."
          },
          "crs": {
            "$ref": "#/components/schemas/AreaCrs"
          },
          "areas": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Area"
            },
            "description": "The areas, in file order."
          },
          "skipped": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A record left out.",
              "required": [
                "index",
                "reason"
              ],
              "properties": {
                "index": {
                  "type": "integer",
                  "description": "Record or feature index in the file.",
                  "minimum": 0
                },
                "reason": {
                  "type": "string",
                  "description": "Why it isn't an area: a null shape, deleted in the .dbf, not a polygon, no ring with area, off the globe."
                }
              },
              "additionalProperties": false
            },
            "description": "Records left out, in file order: the first 100, with a warning counting any more."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sentence."
            },
            "description": "What to check: other layers, the coordinate system's doubt, simplified fill rings, areas with holes or several parts, areas off the dataset."
          }
        },
        "additionalProperties": false
      },
      "CompletionDesignsUpload": {
        "type": "object",
        "description": "Completion designs as multipart/form-data; only file, sheet and include are accepted.",
        "required": [
          "file"
        ],
        "properties": {
          "file": {
            "type": "string",
            "description": "A CSV or .xlsx workbook.",
            "format": "binary"
          },
          "sheet": {
            "type": "string",
            "description": "Workbook sheet name in any case or index from 0; absent, the first. With CSV, a 400."
          },
          "include": {
            "type": "string",
            "description": "JSON text, as [\"sheets\"]: a workbook's answer adds sheet and sheets; any other file's answer is unchanged."
          }
        },
        "additionalProperties": false
      },
      "CompletionDesignsReadRequest": {
        "type": "object",
        "description": "Completion designs in JSON.",
        "required": [
          "csv"
        ],
        "properties": {
          "csv": {
            "type": "string",
            "description": "The CSV or tab-separated file text."
          }
        },
        "additionalProperties": false
      },
      "CompletionDesignRow": {
        "type": "object",
        "description": "Every data row of the completion designs file but blank lines.",
        "required": [
          "id",
          "name",
          "formation",
          "design",
          "issues"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Data row from 0, in file order.",
            "minimum": 0
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Trimmed name, generated Design N without a name column, or null when blank."
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dataset spelling when matched, else the text as written, or null when blank."
          },
          "design": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Index in designs, or null when left out.",
            "minimum": 0
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sentence."
            },
            "description": "Why the row was left out or a value dropped."
          }
        },
        "additionalProperties": false
      },
      "CompletionDesignsRead": {
        "type": "object",
        "description": "Completion designs read from a file; nothing is stored.",
        "required": [
          "count",
          "format",
          "columns",
          "fields",
          "designs",
          "rows",
          "unknown_formations",
          "warnings"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "Number of designs.",
            "minimum": 0
          },
          "format": {
            "type": "string",
            "description": "How the file was read.",
            "enum": [
              "csv",
              "xlsx"
            ]
          },
          "sheet": {
            "type": "string",
            "description": "The sheet read; only with include [\"sheets\"], for a workbook."
          },
          "sheets": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sheet's name; one over 31 characters is cut to 31 and ends in …."
            },
            "description": "Every sheet in workbook order, chartsheets included, so a position is the index sheet takes; only with include [\"sheets\"], for a workbook."
          },
          "columns": {
            "type": "object",
            "description": "Each role and its header as read; null when absent.",
            "required": [
              "name",
              "formation",
              "fluid_bbl_per_ft",
              "fluid_gal_per_ft",
              "proppant_lb_per_ft",
              "fluid_bbl_per_stage",
              "proppant_lb_per_stage",
              "stage_length_ft"
            ],
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Design name header or null."
              },
              "formation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Formation header or null."
              },
              "fluid_bbl_per_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Fluid bbl/ft header or null."
              },
              "fluid_gal_per_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Fluid gal/ft header or null."
              },
              "proppant_lb_per_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Proppant lb/ft header or null."
              },
              "fluid_bbl_per_stage": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Fluid per-stage header or null."
              },
              "proppant_lb_per_stage": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Proppant per-stage header or null."
              },
              "stage_length_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Stage length header or null."
              },
              "clusters_per_stage": {
                "type": "string",
                "description": "Clusters per stage header; only when the file has the column."
              },
              "frac_rate_bbl_per_min": {
                "type": "string",
                "description": "Frac rate header; only when the file has the column."
              }
            },
            "additionalProperties": false
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A header."
            },
            "description": "Headers in file order."
          },
          "designs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignInput"
            },
            "description": "Named designs in first-appearance order, ready to post as designs; formations is always an array."
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompletionDesignRow"
            },
            "description": "Every data row in file order; blank lines are left out."
          },
          "unknown_formations": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One unknown formation, matched in any case.",
              "required": [
                "value",
                "rows"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "description": "First spelling read."
                },
                "rows": {
                  "type": "integer",
                  "description": "Rows left out.",
                  "minimum": 1
                }
              },
              "additionalProperties": false
            },
            "description": "Most rows first, ties in first-seen order."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sentence."
            },
            "description": "Workbook warnings first, then each column with no number in it, rows left out, the warning past 10 designs, and one naming filled stage columns the model set's models don't read."
          }
        },
        "additionalProperties": false
      },
      "AreaSetMeta": {
        "type": "object",
        "description": "An area set's record.",
        "required": [
          "id",
          "name",
          "count",
          "acres",
          "bbox",
          "crs",
          "name_field",
          "file",
          "visibility",
          "created_by",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Its id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Its name, 1 to 100 characters."
          },
          "count": {
            "type": "integer",
            "description": "Areas in it.",
            "minimum": 1
          },
          "acres": {
            "type": "number",
            "description": "Its areas' acres added up, rounded to 0.01."
          },
          "bbox": {
            "type": "array",
            "items": {
              "type": "number",
              "description": "Degrees."
            },
            "description": "West, south, east and north of its areas' outer rings, WGS 84.",
            "minItems": 4,
            "maxItems": 4
          },
          "crs": {
            "$ref": "#/components/schemas/AreaCrs"
          },
          "name_field": {
            "type": [
              "string",
              "null"
            ],
            "description": "The field the areas' names came from, or null."
          },
          "name_fields": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A field, as the file spells it."
            },
            "description": "Only for a set made with name_fields: those fields as the file spells them, in the order sent; name_field is the first."
          },
          "name_separator": {
            "type": "string",
            "description": "Only for a set made with name_fields: what joined their values."
          },
          "file": {
            "anyOf": [
              {
                "type": "object",
                "description": "The uploaded file.",
                "required": [
                  "name",
                  "bytes",
                  "sha256"
                ],
                "properties": {
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The file part's name, or null without one."
                  },
                  "bytes": {
                    "type": "integer",
                    "description": "Its size.",
                    "minimum": 0
                  },
                  "sha256": {
                    "type": "string",
                    "description": "Its SHA-256, hex."
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The uploaded file; null from a JSON body."
          },
          "visibility": {
            "type": "string",
            "description": "private: its signed-in creator only; tenant: every user of the tenant.",
            "enum": [
              "private",
              "tenant"
            ]
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its signed-in creator's email, or null."
          },
          "created_at": {
            "type": "string",
            "description": "When it was kept.",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "description": "When it last changed.",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "AreaSet": {
        "type": "object",
        "description": "An area set with its areas.",
        "required": [
          "id",
          "name",
          "count",
          "acres",
          "bbox",
          "crs",
          "name_field",
          "file",
          "visibility",
          "created_by",
          "created_at",
          "updated_at",
          "areas",
          "skipped",
          "warnings"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Its id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Its name, 1 to 100 characters."
          },
          "count": {
            "type": "integer",
            "description": "Areas in it.",
            "minimum": 1
          },
          "acres": {
            "type": "number",
            "description": "Its areas' acres added up, rounded to 0.01."
          },
          "bbox": {
            "type": "array",
            "items": {
              "type": "number",
              "description": "Degrees."
            },
            "description": "West, south, east and north of its areas' outer rings, WGS 84.",
            "minItems": 4,
            "maxItems": 4
          },
          "crs": {
            "$ref": "#/components/schemas/AreaCrs"
          },
          "name_field": {
            "type": [
              "string",
              "null"
            ],
            "description": "The field the areas' names came from, or null."
          },
          "name_fields": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A field, as the file spells it."
            },
            "description": "Only for a set made with name_fields: those fields as the file spells them, in the order sent; name_field is the first."
          },
          "name_separator": {
            "type": "string",
            "description": "Only for a set made with name_fields: what joined their values."
          },
          "file": {
            "anyOf": [
              {
                "type": "object",
                "description": "The uploaded file.",
                "required": [
                  "name",
                  "bytes",
                  "sha256"
                ],
                "properties": {
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The file part's name, or null without one."
                  },
                  "bytes": {
                    "type": "integer",
                    "description": "Its size.",
                    "minimum": 0
                  },
                  "sha256": {
                    "type": "string",
                    "description": "Its SHA-256, hex."
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The uploaded file; null from a JSON body."
          },
          "visibility": {
            "type": "string",
            "description": "private: its signed-in creator only; tenant: every user of the tenant.",
            "enum": [
              "private",
              "tenant"
            ]
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its signed-in creator's email, or null."
          },
          "created_at": {
            "type": "string",
            "description": "When it was kept.",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "description": "When it last changed.",
            "format": "date-time"
          },
          "areas": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Area"
            },
            "description": "The areas, in file order; in_dataset against the request's model set."
          },
          "skipped": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A record left out.",
              "required": [
                "index",
                "reason"
              ],
              "properties": {
                "index": {
                  "type": "integer",
                  "description": "Record or feature index in the file.",
                  "minimum": 0
                },
                "reason": {
                  "type": "string",
                  "description": "Why it isn't an area."
                }
              },
              "additionalProperties": false
            },
            "description": "On create, the records POST /areas leaves out; on get, empty."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sentence."
            },
            "description": "On create, POST /areas' warnings; on get, the warning for areas outside the model set's bbox, if any."
          }
        },
        "additionalProperties": false
      },
      "AreaSetList": {
        "type": "object",
        "description": "Area sets page.",
        "required": [
          "items",
          "next_cursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AreaSetMeta"
            },
            "description": "Newest first."
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Next page, null at end."
          }
        },
        "additionalProperties": false
      },
      "CreateAreaSetRequest": {
        "type": "object",
        "description": "A file to keep as an area set, in a JSON body: one of shapefile, geojson, kml or kmz.",
        "required": [
          "name"
        ],
        "properties": {
          "shapefile": {
            "type": "string",
            "description": "As in POST /areas: a zipped shapefile in base64.",
            "contentEncoding": "base64",
            "contentMediaType": "application/zip"
          },
          "geojson": {
            "type": "object",
            "description": "As in POST /areas: a GeoJSON FeatureCollection, Feature, Polygon or MultiPolygon."
          },
          "kml": {
            "type": "string",
            "description": "As in POST /areas: a KML file's text."
          },
          "kmz": {
            "type": "string",
            "description": "As in POST /areas: a KMZ in base64.",
            "contentEncoding": "base64",
            "contentMediaType": "application/vnd.google-earth.kmz"
          },
          "crs": {
            "type": [
              "string",
              "integer",
              "null"
            ],
            "description": "As in POST /areas: the file's coordinate system as an EPSG code."
          },
          "name_field": {
            "type": [
              "string",
              "null"
            ],
            "description": "As in POST /areas.",
            "maxLength": 100
          },
          "name_fields": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "description": "A field name.",
              "minLength": 1,
              "maxLength": 100
            },
            "minItems": 1,
            "maxItems": 5,
            "description": "As in POST /areas."
          },
          "name_separator": {
            "type": [
              "string",
              "null"
            ],
            "description": "As in POST /areas.",
            "maxLength": 8
          },
          "name": {
            "type": "string",
            "description": "The set's name.",
            "minLength": 1,
            "maxLength": 100
          },
          "visibility": {
            "type": "string",
            "description": "private (the default) answers only its signed-in creator; tenant every user of the tenant.",
            "enum": [
              "private",
              "tenant"
            ]
          }
        },
        "additionalProperties": false
      },
      "AreaSetUpload": {
        "type": "object",
        "description": "A multipart/form-data upload to keep: one file part and text parts; any other part, or a second file, is a 400.",
        "required": [
          "file",
          "name"
        ],
        "properties": {
          "file": {
            "type": "string",
            "description": "As in POST /areas; the part's file name is kept with the set.",
            "format": "binary"
          },
          "crs": {
            "type": "string",
            "description": "As in POST /areas."
          },
          "name_field": {
            "type": "string",
            "description": "As in POST /areas."
          },
          "name_fields": {
            "type": "string",
            "description": "As in POST /areas, as JSON text."
          },
          "name_separator": {
            "type": "string",
            "description": "As in POST /areas."
          },
          "name": {
            "type": "string",
            "description": "The set's name, 1 to 100 characters."
          },
          "visibility": {
            "type": "string",
            "description": "private or tenant, as in the JSON body."
          }
        },
        "additionalProperties": false
      },
      "AreaSetPatch": {
        "type": "object",
        "description": "Fields to change, at least one.",
        "required": [],
        "properties": {
          "name": {
            "type": "string",
            "description": "The new name.",
            "minLength": 1,
            "maxLength": 100
          },
          "visibility": {
            "type": "string",
            "description": "private (its signed-in creator only) or tenant.",
            "enum": [
              "private",
              "tenant"
            ]
          }
        },
        "additionalProperties": false,
        "minProperties": 1
      },
      "InventoryColumn": {
        "type": "object",
        "description": "An inventory upload column.",
        "required": [
          "key",
          "roles",
          "header",
          "headers",
          "field",
          "unit",
          "required",
          "reads_with",
          "description",
          "aliases"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "Stable column key; its primary reader role."
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A reader role."
            },
            "description": "Roles this column can fill, primary first; Heelpoint also fills shl when Top Hole is absent."
          },
          "header": {
            "type": "string",
            "description": "The imperial template header."
          },
          "headers": {
            "type": "object",
            "description": "Headers by unit system.",
            "required": [
              "imperial",
              "metric"
            ],
            "properties": {
              "imperial": {
                "type": "string",
                "description": "Imperial template header."
              },
              "metric": {
                "type": "string",
                "description": "Metric template header."
              }
            },
            "additionalProperties": false
          },
          "field": {
            "type": [
              "string",
              "null"
            ],
            "description": "A shapefile's attribute name of up to 10 characters, or null for CSV positions."
          },
          "unit": {
            "anyOf": [
              {
                "type": "object",
                "description": "Units by system.",
                "required": [
                  "imperial",
                  "metric"
                ],
                "properties": {
                  "imperial": {
                    "type": "string",
                    "description": "Imperial unit."
                  },
                  "metric": {
                    "type": "string",
                    "description": "Metric unit."
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The units in CSV, GeoJSON and Excel headers, or null for columns without unit headers; a shapefile's field name carries none (POST /inventories/read's Units text says how it reads)."
          },
          "required": {
            "type": "string",
            "description": "yes: required unless the request sends formation; csv: required for CSV lateral ends, with Top Hole able to stand in for Heelpoint; no: optional.",
            "enum": [
              "yes",
              "csv",
              "no"
            ]
          },
          "reads_with": {
            "type": [
              "string",
              "null"
            ],
            "description": "Request flag needed to read this column, or null."
          },
          "description": {
            "type": "string",
            "description": "What the value means and how it is read."
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A normalized alias."
            },
            "description": "Lowercased letters-and-digits names the upload compares, in match order."
          }
        },
        "additionalProperties": false
      },
      "InventoryColumnsResponse": {
        "type": "object",
        "description": "The inventory column catalog.",
        "required": [
          "columns"
        ],
        "properties": {
          "columns": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InventoryColumn"
            },
            "description": "Columns in template order."
          }
        },
        "additionalProperties": false
      },
      "InventoryWriteRequest": {
        "type": "object",
        "description": "Download wells as an inventory file.",
        "required": [
          "wells"
        ],
        "properties": {
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WellInput"
            },
            "minItems": 1,
            "description": "The checked wells to write, at most GET /dataset limits.plan_wells. Values use ft, bbl/ft and lb/ft regardless of output units."
          },
          "format": {
            "type": "string",
            "description": "The file format.",
            "enum": [
              "csv",
              "geojson",
              "shapefile"
            ],
            "default": "csv"
          },
          "units": {
            "type": "string",
            "description": "The output units: imperial ft, bbl/ft, lb/ft or metric m, m3/m, t/m.",
            "enum": [
              "imperial",
              "metric"
            ],
            "default": "imperial"
          },
          "name": {
            "type": "string",
            "description": "The filename stem, 1 to 100 characters once trimmed; characters outside [A-Za-z0-9 ._-] become underscores.",
            "minLength": 1,
            "maxLength": 100,
            "default": "inventory"
          },
          "eur_water": {
            "type": "boolean",
            "default": false,
            "description": "Also write each well's flat decline settings into the water columns, so they read back as decline.water with POST /inventories/read eur_water: true. Default false, as on the read."
          }
        },
        "additionalProperties": false
      },
      "InventoryRequest": {
        "type": "object",
        "description": "Send csv, geojson or shapefile, one of them, and options.",
        "required": [],
        "properties": {
          "csv": {
            "type": "string",
            "description": "The CSV (or tab-separated) file's text. Where you can, upload the file itself as multipart/form-data instead."
          },
          "geojson": {
            "type": "object",
            "description": "A GeoJSON FeatureCollection, Feature, LineString or MultiLineString of well paths, each heel first. Coordinates in degrees are WGS 84 (RFC 7946); others need a crs member or crs, or are detected."
          },
          "shapefile": {
            "type": "string",
            "description": "A zipped line shapefile (.shp, .dbf and .prj; .cpg and .shx optional) in base64: RFC 4648, padded, with no line breaks or data: prefix.",
            "contentEncoding": "base64",
            "contentMediaType": "application/zip"
          },
          "crs": {
            "type": [
              "string",
              "integer",
              "null"
            ],
            "description": "The file's coordinate system as an EPSG code (EPSG:4267, epsg:4267 or 4267). A CSV takes EPSG:4326, EPSG:4269 (read as WGS 84) or EPSG:4267 (NAD27, shifted with NADCON).\n\nFor lines it overrides the file's own and detection, and is one of EPSG:2275, EPSG:2276, EPSG:2277, EPSG:2278, EPSG:2279, EPSG:2257, EPSG:2258, EPSG:2259, EPSG:32137, EPSG:32138, EPSG:32139, EPSG:32140, EPSG:32141, EPSG:32112, EPSG:32113, EPSG:32114, EPSG:6578, EPSG:6588, EPSG:3081, EPSG:3082, EPSG:3083, EPSG:5070, EPSG:3857, EPSG:26913, EPSG:26914, EPSG:32613, EPSG:32614, EPSG:4326, EPSG:4269, EPSG:32037, EPSG:32038, EPSG:32039, EPSG:32040, EPSG:32041, EPSG:32012, EPSG:32013, EPSG:32014, EPSG:26713, EPSG:26714, EPSG:4267."
          },
          "units": {
            "type": "string",
            "description": "The file's unit system: imperial ft, bbl/ft, lb/ft, or metric m, m3/m, t/m, with frac rate in bbl/min, or m3/min in metric; a unit in a column's header wins. Any other value is a 400 on units.",
            "enum": [
              "imperial",
              "metric"
            ],
            "default": "imperial"
          },
          "columns": {
            "type": "object",
            "description": "Columns to read a role from instead of the one found by name: the exact column name, else in any case. A column the file lacks is a 400 with details.fields.",
            "required": [],
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The column of each well's name, kept in rows, and in wells with well_names: true."
              },
              "formation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its target formation."
              },
              "tvd_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its TVD: ft, else as units or its header says."
              },
              "drill_date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its drill date, only with til_from_dates."
              },
              "completion_date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its completion date, only with til_from_dates."
              },
              "til_date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its TIL date."
              },
              "lateral_length_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its stated lateral length, checked against the drawn one: ft, else as units or its header says."
              },
              "shl_lat": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "CSV only: of the heel's latitude (or the surface hole's); the surface hole's when the heel is read too."
              },
              "shl_lng": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "CSV only: of the heel's longitude (or the surface hole's); the surface hole's when the heel is read too."
              },
              "heel_lat": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "CSV only: of the heel's latitude, read apart from shl when the file has a surface hole too; else shl reads it."
              },
              "heel_lng": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "CSV only: of the heel's longitude, read apart from shl when the file has a surface hole too; else shl reads it."
              },
              "bhl_lat": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "CSV only: of the bottom hole's (toe's) latitude."
              },
              "bhl_lng": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "CSV only: of the bottom hole's (toe's) longitude."
              },
              "fluid_bbl_per_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its fluid per lateral length: bbl/ft, else as units or its header says."
              },
              "proppant_lb_per_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its proppant per lateral length: lb/ft, else as units or its header says."
              },
              "stage_length_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its stage length: ft, else as units or its header says."
              },
              "clusters_per_stage": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its clusters per stage."
              },
              "frac_rate_bbl_per_min": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its frac rate: bbl/min, else as units or its header says."
              },
              "scenario": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its scenario name."
              },
              "pad": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its pad."
              },
              "eur_years": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its years to EUR."
              },
              "oil_min_b": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its oil b_min."
              },
              "oil_max_b": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its oil b_max."
              },
              "oil_terminal_decline": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its oil terminal decline."
              },
              "gas_min_b": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its gas b_min."
              },
              "gas_max_b": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its gas b_max."
              },
              "gas_terminal_decline": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its gas terminal decline."
              },
              "water_min_b": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its water b_min, only with eur_water: true."
              },
              "water_max_b": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its water b_max, only with eur_water: true."
              },
              "water_terminal_decline": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its water terminal decline, only with eur_water: true."
              },
              "completion_name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Of its completion's name, only with designs_from_rows: true."
              }
            },
            "additionalProperties": false
          },
          "column_hints": {
            "type": "object",
            "propertyNames": {
              "enum": [
                "name",
                "formation",
                "tvd_ft",
                "til_date",
                "lateral_length_ft",
                "shl_lat",
                "shl_lng",
                "heel_lat",
                "heel_lng",
                "bhl_lat",
                "bhl_lng",
                "fluid_bbl_per_ft",
                "proppant_lb_per_ft",
                "stage_length_ft",
                "clusters_per_stage",
                "frac_rate_bbl_per_min",
                "scenario",
                "pad",
                "eur_years",
                "oil_min_b",
                "oil_max_b",
                "oil_terminal_decline",
                "gas_min_b",
                "gas_max_b",
                "gas_terminal_decline",
                "water_min_b",
                "water_max_b",
                "water_terminal_decline",
                "drill_date",
                "completion_date",
                "completion_name"
              ]
            },
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "pattern": "\\S"
              },
              "minItems": 1,
              "maxItems": 20
            },
            "description": "Column names to try per role, as {\"pad\": [\"Pad ID\", \"Lease\"]}, for roles that columns and name matching leave unread: the first the file has that no role reads or finds.\n\nA name the file lacks is skipped; an unknown role or a bad list is a 400 on column_hints.<role>. Dropped: position roles in a line file, water roles without eur_water (with a warning naming the columns they find), date roles without til_from_dates, completion_name without designs_from_rows."
          },
          "formations": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "maxProperties": 100,
            "description": "The file's formation names (any case) mapped to formations in GET /formations, as {\"WFMP A\": \"WOLFCAMP A\"}: unknown_formations says which to map. A formation this model set lacks is skipped with a warning naming it."
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "The formation of rows whose formation is blank, or of every row when the file has no formation column (any case; GET /formations lists them)."
          },
          "eur_water": {
            "type": "boolean",
            "default": false,
            "description": "Read the water_min_b, water_max_b and water_terminal_decline columns: the wells carry `decline.water`, so post them with `\"eur_water\": true`. Absent, those columns aren't read and a warning names them, since a file posted as it comes would be a 400."
          },
          "well_names": {
            "type": "boolean",
            "default": false,
            "description": "Write each kept well's trimmed name on `wells[].name`, for POST /forecasts, POST /plans and POST /inventories/write: other routes that take wells answer 400 on a name. A blank one is left off, and one over 60 characters once trimmed is left off with one issue on its row, keeping the well."
          },
          "til_from_dates": {
            "type": "object",
            "description": "Fill a missing TIL date from completion, else drill dates; an empty object uses 42 days after each.",
            "required": [],
            "properties": {
              "drill_to_completion_days": {
                "type": "integer",
                "description": "Days from the drill date to completion.",
                "minimum": 0,
                "maximum": 365,
                "default": 42
              },
              "completion_to_til_days": {
                "type": "integer",
                "description": "Days from the completion date to TIL.",
                "minimum": 0,
                "maximum": 365,
                "default": 42
              }
            },
            "additionalProperties": false
          },
          "designs_from_rows": {
            "type": "boolean",
            "default": false,
            "description": "Read a row that repeats a well with a completion the well lacks as that well under another design: the answer adds designs and each row's design when some well has rows of two completions, else is the answer without it. See Several rows per well."
          }
        },
        "additionalProperties": false
      },
      "InventoryUpload": {
        "type": "object",
        "description": "A multipart/form-data upload: one file part and optional text parts; any other part, or a second file, is a 400.",
        "required": [
          "file"
        ],
        "properties": {
          "file": {
            "type": "string",
            "description": "The CSV, Excel workbook (.xlsx), GeoJSON file or zipped line shapefile, as a file part (curl -F file=@wells.csv). Text may come as a text part (curl -F file=<wells.csv), read as UTF-8: send Windows-1252 as a file part.\n\nAn .xls (an OLE file, or a workbook saved with a password) is a 400. A zip with [Content_Types].xml is a workbook, any other zip a line shapefile; else a JSON object with a type is GeoJSON, anything else a CSV.",
            "format": "binary"
          },
          "crs": {
            "type": "string",
            "description": "As crs in the JSON body: an EPSG code."
          },
          "formation": {
            "type": "string",
            "description": "As formation in the JSON body."
          },
          "units": {
            "type": "string",
            "description": "As units in the JSON body, as plain text: imperial or metric."
          },
          "columns": {
            "type": "string",
            "description": "As columns in the JSON body, as JSON text: {\"name\": \"Lease Well\"}."
          },
          "column_hints": {
            "type": "string",
            "description": "As column_hints in the JSON body, as JSON text: {\"pad\": [\"Pad ID\", \"Lease\"]}."
          },
          "formations": {
            "type": "string",
            "description": "As formations in the JSON body, as JSON text: {\"WFMP A\": \"WOLFCAMP A\"}."
          },
          "eur_water": {
            "type": "string",
            "description": "As eur_water in the JSON body, as JSON text: true or false."
          },
          "well_names": {
            "type": "string",
            "description": "As well_names in the JSON body, as JSON text: true or false."
          },
          "sheet": {
            "type": "string",
            "description": "An Excel workbook's sheet: its name (exact, else in any case) or its index from 0, as Wells or 0; default the first, with a warning when there are more. A 400 with any other file."
          },
          "include": {
            "type": "string",
            "description": "JSON text, as [\"sheets\"]: a workbook's answer adds sheet and sheets; any other file's answer is unchanged."
          },
          "til_from_dates": {
            "type": "string",
            "description": "As til_from_dates in the JSON body, as JSON text: {\"completion_to_til_days\": 30}."
          },
          "designs_from_rows": {
            "type": "string",
            "description": "As designs_from_rows in the JSON body, as JSON text: true or false."
          }
        },
        "additionalProperties": false
      },
      "InventoryRow": {
        "type": "object",
        "description": "What became of a row of the file.",
        "required": [
          "id",
          "name",
          "well",
          "lateral_length_ft",
          "in_dataset",
          "issues"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Its row in the file from 0: a CSV's data row (blank lines not counted), or a line's record or feature index.",
            "minimum": 0
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its name from the name column, or null."
          },
          "well": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Its index in wells, or null when it was left out (issues says why).",
            "minimum": 0
          },
          "design": {
            "type": "integer",
            "description": "Its index in designs: only in an answer with designs, on every kept row.",
            "minimum": 0
          },
          "lateral_length_ft": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Feet from the heel, else shl, to bhl, rounded; null without a usable position."
          },
          "in_dataset": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "True when an end lies in GET /dataset's bbox; null without a usable position."
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sentence."
            },
            "description": "Why it was left out, or what was dropped or doubted in a well kept; empty when it read cleanly."
          },
          "til_from": {
            "type": [
              "string",
              "null"
            ],
            "description": "Where its TIL date came from, only with til_from_dates; null without an accepted date or when left out.",
            "enum": [
              "file",
              "completion_date",
              "drill_date",
              null
            ]
          }
        },
        "additionalProperties": false
      },
      "InventoryResponse": {
        "type": "object",
        "description": "Planned wells read from a file.",
        "required": [
          "count",
          "format",
          "crs",
          "columns",
          "fields",
          "wells",
          "rows",
          "unknown_formations",
          "warnings"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "Wells read: the length of wells.",
            "minimum": 0
          },
          "format": {
            "type": "string",
            "description": "How the file was read.",
            "enum": [
              "csv",
              "xlsx",
              "geojson",
              "shapefile"
            ]
          },
          "sheet": {
            "type": "string",
            "description": "The sheet read; only with include [\"sheets\"], for a workbook."
          },
          "sheets": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sheet's name; one over 31 characters is cut to 31 and ends in …."
            },
            "description": "Every sheet in workbook order, chartsheets included, so a position is the index sheet takes; only with include [\"sheets\"], for a workbook."
          },
          "crs": {
            "$ref": "#/components/schemas/AreaCrs"
          },
          "columns": {
            "type": "object",
            "description": "The column each role was read from, or null when the file has none.",
            "required": [
              "name",
              "formation",
              "tvd_ft",
              "til_date",
              "lateral_length_ft",
              "shl_lat",
              "shl_lng",
              "bhl_lat",
              "bhl_lng"
            ],
            "properties": {
              "drill_date": {
                "type": "string",
                "description": "Drill dates; only with til_from_dates, when the file has the column."
              },
              "completion_date": {
                "type": "string",
                "description": "Completion dates; only with til_from_dates, when the file has the column."
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The column names came from, or null."
              },
              "formation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Formations'."
              },
              "tvd_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "TVDs'."
              },
              "til_date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "TIL dates'."
              },
              "lateral_length_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Stated lateral lengths'."
              },
              "shl_lat": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A CSV's shl latitudes'; null for lines."
              },
              "shl_lng": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A CSV's shl longitudes'; null for lines."
              },
              "heel_lat": {
                "type": "string",
                "description": "A CSV's heel latitudes'; only when the heel is read apart from shl."
              },
              "heel_lng": {
                "type": "string",
                "description": "A CSV's heel longitudes'; only when the heel is read apart from shl."
              },
              "bhl_lat": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A CSV's bhl latitudes'; null for lines."
              },
              "bhl_lng": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A CSV's bhl longitudes'; null for lines."
              },
              "fluid_bbl_per_ft": {
                "type": "string",
                "description": "Fluid per ft's; only when the file has the column."
              },
              "proppant_lb_per_ft": {
                "type": "string",
                "description": "Proppant per ft's; only when the file has the column."
              },
              "stage_length_ft": {
                "type": "string",
                "description": "Stage lengths'; only when the file has the column."
              },
              "clusters_per_stage": {
                "type": "string",
                "description": "Clusters per stage; only when the file has the column."
              },
              "frac_rate_bbl_per_min": {
                "type": "string",
                "description": "Frac rates'; only when the file has the column."
              },
              "scenario": {
                "type": "string",
                "description": "Inventory names'; only when the file has the column."
              },
              "pad": {
                "type": "string",
                "description": "Pad names'; only when the file has the column."
              },
              "eur_years": {
                "type": "string",
                "description": "Years to EUR'; only when the file has the column."
              },
              "oil_min_b": {
                "type": "string",
                "description": "Oil b_min's; only when the file has the column."
              },
              "oil_max_b": {
                "type": "string",
                "description": "Oil b_max's; only when the file has the column."
              },
              "oil_terminal_decline": {
                "type": "string",
                "description": "Oil terminal declines'; only when the file has the column."
              },
              "gas_min_b": {
                "type": "string",
                "description": "Gas b_min's; only when the file has the column."
              },
              "gas_max_b": {
                "type": "string",
                "description": "Gas b_max's; only when the file has the column."
              },
              "gas_terminal_decline": {
                "type": "string",
                "description": "Gas terminal declines'; only when the file has the column."
              },
              "water_min_b": {
                "type": "string",
                "description": "Water b_min's; only with eur_water: true, when the file has the column."
              },
              "water_max_b": {
                "type": "string",
                "description": "Water b_max's; only with eur_water: true, when the file has the column."
              },
              "water_terminal_decline": {
                "type": "string",
                "description": "Water terminal declines'; only with eur_water: true, when the file has the column."
              },
              "completion_name": {
                "type": "string",
                "description": "Completion names'; only in an answer with designs, when the file has the column."
              }
            },
            "additionalProperties": false
          },
          "units": {
            "type": "object",
            "description": "Units read, only when units was sent, a shapefile's UNITS attribute is read or a resolved column header names a recognized unit.",
            "required": [
              "system",
              "columns"
            ],
            "properties": {
              "system": {
                "type": "string",
                "description": "A shapefile's UNITS system when it has one, else the request's, imperial when absent.",
                "enum": [
                  "imperial",
                  "metric"
                ]
              },
              "columns": {
                "type": "object",
                "description": "Only roles whose column the file has.",
                "required": [],
                "properties": {
                  "tvd_ft": {
                    "type": "object",
                    "description": "The unit read for this column.",
                    "required": [
                      "unit",
                      "from"
                    ],
                    "properties": {
                      "unit": {
                        "type": "string",
                        "description": "The unit read."
                      },
                      "from": {
                        "type": "string",
                        "description": "Where the unit came from: file is a shapefile's UNITS attribute.",
                        "enum": [
                          "header",
                          "file",
                          "request",
                          "default"
                        ]
                      }
                    },
                    "additionalProperties": false
                  },
                  "lateral_length_ft": {
                    "type": "object",
                    "description": "The unit read for this column.",
                    "required": [
                      "unit",
                      "from"
                    ],
                    "properties": {
                      "unit": {
                        "type": "string",
                        "description": "The unit read."
                      },
                      "from": {
                        "type": "string",
                        "description": "Where the unit came from: file is a shapefile's UNITS attribute.",
                        "enum": [
                          "header",
                          "file",
                          "request",
                          "default"
                        ]
                      }
                    },
                    "additionalProperties": false
                  },
                  "fluid_bbl_per_ft": {
                    "type": "object",
                    "description": "The unit read for this column.",
                    "required": [
                      "unit",
                      "from"
                    ],
                    "properties": {
                      "unit": {
                        "type": "string",
                        "description": "The unit read."
                      },
                      "from": {
                        "type": "string",
                        "description": "Where the unit came from: file is a shapefile's UNITS attribute.",
                        "enum": [
                          "header",
                          "file",
                          "request",
                          "default"
                        ]
                      }
                    },
                    "additionalProperties": false
                  },
                  "proppant_lb_per_ft": {
                    "type": "object",
                    "description": "The unit read for this column.",
                    "required": [
                      "unit",
                      "from"
                    ],
                    "properties": {
                      "unit": {
                        "type": "string",
                        "description": "The unit read."
                      },
                      "from": {
                        "type": "string",
                        "description": "Where the unit came from: file is a shapefile's UNITS attribute.",
                        "enum": [
                          "header",
                          "file",
                          "request",
                          "default"
                        ]
                      }
                    },
                    "additionalProperties": false
                  },
                  "stage_length_ft": {
                    "type": "object",
                    "description": "The unit read for this column.",
                    "required": [
                      "unit",
                      "from"
                    ],
                    "properties": {
                      "unit": {
                        "type": "string",
                        "description": "The unit read."
                      },
                      "from": {
                        "type": "string",
                        "description": "Where the unit came from: file is a shapefile's UNITS attribute.",
                        "enum": [
                          "header",
                          "file",
                          "request",
                          "default"
                        ]
                      }
                    },
                    "additionalProperties": false
                  },
                  "frac_rate_bbl_per_min": {
                    "type": "object",
                    "description": "The unit read for this column.",
                    "required": [
                      "unit",
                      "from"
                    ],
                    "properties": {
                      "unit": {
                        "type": "string",
                        "description": "The unit read."
                      },
                      "from": {
                        "type": "string",
                        "description": "Where the unit came from: file is a shapefile's UNITS attribute.",
                        "enum": [
                          "header",
                          "file",
                          "request",
                          "default"
                        ]
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A column name."
            },
            "description": "The file's columns (a CSV's header, or the lines' attributes), in file order."
          },
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WellInput"
            },
            "description": "The wells, in file order, to post as wells to POST /forecasts or POST /plans. Posting a decline needs `\"eur\": true`; posting wells read with eur_water: true needs `\"eur_water\": true`.\n\nEach has shl (the heel, or the surface hole with heel), heel when the file has both, bhl, formation, and typed_lateral from a stated lateral length unless it is both over 5% off the drawn one and outside 100 to 50,000 ft. tvd_ft, til_date, fluid_bbl_per_ft, proppant_lb_per_ft, stage_length_ft, clusters_per_stage, frac_rate_bbl_per_min, scenario, pad and decline come when the file has good ones; name with well_names: true."
          },
          "designs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DesignInput"
            },
            "description": "Only with designs_from_rows when some well has rows of two completions: the file's completions in first-seen order, at most 10, to send as designs to POST /plans with wells."
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InventoryRow"
            },
            "description": "Every row of the file, in file order."
          },
          "unknown_formations": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A formation this dataset lacks.",
              "required": [
                "value",
                "rows"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "description": "A formation name in the file."
                },
                "rows": {
                  "type": "integer",
                  "description": "Rows naming it.",
                  "minimum": 1
                }
              },
              "additionalProperties": false
            },
            "description": "Formation names that matched nothing, most rows first: map them in formations."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sentence."
            },
            "description": "What to check: a surface hole read as shl, rows left out or with issues, unknown formations, other layers, the coordinate system's doubt, wells without an inventory name, more names than a plan takes.\n\nAlso unread decline columns (water's without eur_water: true; condensate's unless the set's oil slot holds condensate; oil's when condensate's fill its roles; a stream's the set doesn't serve) and filled stage columns the set's models don't read."
          }
        },
        "additionalProperties": false
      },
      "PadsReadRequest": {
        "type": "object",
        "description": "Send exactly one of shapefile, geojson, kml or kmz, and options.",
        "required": [],
        "properties": {
          "shapefile": {
            "type": "string",
            "description": "As POST /areas takes it: a zipped shapefile in base64. Where you can, upload the file itself as multipart/form-data instead.",
            "contentEncoding": "base64",
            "contentMediaType": "application/zip"
          },
          "geojson": {
            "type": "object",
            "description": "As POST /areas takes it: a GeoJSON FeatureCollection, Feature, Polygon or MultiPolygon of pad outlines."
          },
          "kml": {
            "type": "string",
            "description": "As POST /areas takes it: a KML file's text."
          },
          "kmz": {
            "type": "string",
            "description": "As POST /areas takes it: a KMZ in base64. Where you can, upload the file itself as multipart/form-data instead.",
            "contentEncoding": "base64",
            "contentMediaType": "application/vnd.google-earth.kmz"
          },
          "crs": {
            "type": [
              "string",
              "integer",
              "null"
            ],
            "description": "As POST /areas takes it: the file's coordinate system as an EPSG code."
          },
          "name_field": {
            "type": [
              "string",
              "null"
            ],
            "description": "As POST /areas takes it: the field (any case) whose value names each pad.",
            "maxLength": 100
          },
          "name_fields": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string",
              "description": "A field name.",
              "minLength": 1,
              "maxLength": 100
            },
            "minItems": 1,
            "maxItems": 5,
            "description": "As POST /areas takes it: fields whose values, joined, name each pad."
          },
          "name_separator": {
            "type": [
              "string",
              "null"
            ],
            "description": "As POST /areas takes it.",
            "maxLength": 8
          },
          "columns": {
            "type": "object",
            "description": "Fields to read a role from instead of the one found by name: the exact field name, else in any case. A field the file lacks is a 400 with details.fields.",
            "required": [],
            "properties": {
              "formation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's formation."
              },
              "til_date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's til_date."
              },
              "lateral_length_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's lateral_length_ft."
              },
              "tvd_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's tvd_ft."
              },
              "fluid_bbl_per_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's fluid_bbl_per_ft."
              },
              "proppant_lb_per_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's proppant_lb_per_ft."
              },
              "wells_per_section": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's wells_per_section."
              },
              "spacing_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's spacing_ft."
              },
              "azimuth_deg": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's azimuth_deg."
              },
              "setback_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's setback_ft."
              },
              "landing_fraction": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's landing_fraction."
              },
              "stage_length_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's stage_length_ft."
              },
              "clusters_per_stage": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's clusters_per_stage."
              },
              "frac_rate_bbl_per_min": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field of each pad's frac_rate_bbl_per_min."
              }
            },
            "additionalProperties": false
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "The formation of pads whose formation is blank, or of every pad when the file has no formation field (any case; GET /formations lists them)."
          },
          "wells_per_section": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Wells per section for pads without their own (or a spacing that gives one); default 6.",
            "minimum": 1,
            "maximum": 52
          }
        },
        "additionalProperties": false
      },
      "PadsUpload": {
        "type": "object",
        "description": "A multipart/form-data upload: one file part and optional text parts; any other part, or a second file, is a 400.",
        "required": [
          "file"
        ],
        "properties": {
          "file": {
            "type": "string",
            "description": "The zipped shapefile (.zip), GeoJSON, KML or KMZ file, as a file part, as POST /areas takes it.",
            "format": "binary"
          },
          "crs": {
            "type": "string",
            "description": "As crs in the JSON body: an EPSG code."
          },
          "name_field": {
            "type": "string",
            "description": "As name_field in the JSON body."
          },
          "name_fields": {
            "type": "string",
            "description": "As name_fields in the JSON body, as JSON text."
          },
          "name_separator": {
            "type": "string",
            "description": "As name_separator in the JSON body."
          },
          "formation": {
            "type": "string",
            "description": "As formation in the JSON body."
          },
          "columns": {
            "type": "string",
            "description": "As columns in the JSON body, as JSON text: {\"formation\": \"Zone\"}."
          },
          "wells_per_section": {
            "type": "string",
            "description": "As wells_per_section in the JSON body, as JSON text: 6."
          }
        },
        "additionalProperties": false
      },
      "PadRead": {
        "type": "object",
        "description": "What became of a polygon of the file.",
        "required": [
          "id",
          "name",
          "outline",
          "acres",
          "azimuth_deg",
          "wells_per_section",
          "formation",
          "lateral_length_ft",
          "setback_ft",
          "til_date",
          "fluid_bbl_per_ft",
          "proppant_lb_per_ft",
          "tvd_ft",
          "landing_fraction",
          "wells",
          "issues",
          "left_out"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Its record (shapefile) or feature (GeoJSON) index in the file, from 0: its area's id.",
            "minimum": 0
          },
          "name": {
            "type": "string",
            "description": "Its name: the area's from the name field or fields, trimmed, else Pad <id + 1>; its wells' pad."
          },
          "outline": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/LngLat"
            },
            "description": "The area's fill.polygon, open: the ring its wells fill when the area is one part without holes; null when it can't be filled."
          },
          "area": {
            "$ref": "#/components/schemas/AreaGeometry",
            "description": "The area's geometry, which its wells are laid in, when it has holes or several parts."
          },
          "acres": {
            "type": "number",
            "description": "Its area's acres, holes taken out."
          },
          "azimuth_deg": {
            "type": "number",
            "description": "The azimuth its wells run at: its own, else its outline's long axis."
          },
          "wells_per_section": {
            "type": "integer",
            "description": "Wells per section its bench lays: its own, else its spacing's, else the request's.",
            "minimum": 1,
            "maximum": 52
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its formation, as GET /formations names it, or null when blank without the request's, or unknown."
          },
          "lateral_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Its wells' lateral length, ft, or null for edge to edge."
          },
          "setback_ft": {
            "type": "number",
            "description": "Its lease-line setback, ft.",
            "minimum": 0
          },
          "til_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its TIL date, or null.",
            "format": "date"
          },
          "fluid_bbl_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Its fluid per lateral ft, or null."
          },
          "proppant_lb_per_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Its proppant per lateral ft, or null."
          },
          "stage_length_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Its stage length, ft, or null; only when the file has the field."
          },
          "clusters_per_stage": {
            "type": [
              "number",
              "null"
            ],
            "description": "Its clusters per stage, or null; only when the file has the field."
          },
          "frac_rate_bbl_per_min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Its frac rate, bbl/min, or null; only when the file has the field."
          },
          "tvd_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "Its TVD, ft, or null."
          },
          "landing_fraction": {
            "type": [
              "number",
              "null"
            ],
            "description": "Its landing fraction, 0 at the formation top to 1 at its base, or null."
          },
          "wells": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "An index in wells.",
              "minimum": 0
            },
            "description": "Its wells' indexes in wells, in fill order; empty when left out."
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sentence."
            },
            "description": "What was dropped or doubted, and last why it was left out; empty when it read cleanly."
          },
          "left_out": {
            "type": "boolean",
            "description": "True when it lays no wells; the last issue says why."
          }
        },
        "additionalProperties": false
      },
      "PadsReadResponse": {
        "type": "object",
        "description": "Pads read from a file, and their wells.",
        "required": [
          "count",
          "wells_count",
          "crs",
          "name_field",
          "fields",
          "columns",
          "unknown_formations",
          "skipped",
          "warnings",
          "pads",
          "wells",
          "pad_values"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "Pads kept: those not left out.",
            "minimum": 0
          },
          "wells_count": {
            "type": "integer",
            "description": "Wells laid: the length of wells.",
            "minimum": 0
          },
          "crs": {
            "$ref": "#/components/schemas/AreaCrs"
          },
          "name_field": {
            "type": [
              "string",
              "null"
            ],
            "description": "The field the names came from, or null."
          },
          "name_fields": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A field, as the file spells it."
            },
            "description": "As POST /areas gives them, only when the request sent name_fields: those fields as the file spells them, in the order sent; name_field is the first."
          },
          "name_separator": {
            "type": "string",
            "description": "As POST /areas gives them, only when the request sent name_fields: what joined their values."
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A field name."
            },
            "description": "The attributes the areas carry, in file order, as POST /areas gives them."
          },
          "columns": {
            "type": "object",
            "description": "The field each role was read from, or null when the file has none.",
            "required": [
              "formation",
              "til_date",
              "lateral_length_ft",
              "tvd_ft",
              "fluid_bbl_per_ft",
              "proppant_lb_per_ft",
              "wells_per_section",
              "spacing_ft",
              "azimuth_deg",
              "setback_ft",
              "landing_fraction"
            ],
            "properties": {
              "formation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field formation was read from, or null."
              },
              "til_date": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field til_date was read from, or null."
              },
              "lateral_length_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field lateral_length_ft was read from, or null."
              },
              "tvd_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field tvd_ft was read from, or null."
              },
              "fluid_bbl_per_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field fluid_bbl_per_ft was read from, or null."
              },
              "proppant_lb_per_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field proppant_lb_per_ft was read from, or null."
              },
              "wells_per_section": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field wells_per_section was read from, or null."
              },
              "spacing_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field spacing_ft was read from, or null."
              },
              "azimuth_deg": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field azimuth_deg was read from, or null."
              },
              "setback_ft": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field setback_ft was read from, or null."
              },
              "landing_fraction": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The field landing_fraction was read from, or null."
              },
              "stage_length_ft": {
                "type": "string",
                "description": "The field stage_length_ft was read from; only when the file has it or columns names it."
              },
              "clusters_per_stage": {
                "type": "string",
                "description": "The field clusters_per_stage was read from; only when the file has it or columns names it."
              },
              "frac_rate_bbl_per_min": {
                "type": "string",
                "description": "The field frac_rate_bbl_per_min was read from; only when the file has it or columns names it."
              }
            },
            "additionalProperties": false
          },
          "unknown_formations": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A formation this dataset lacks.",
              "required": [
                "value",
                "pads"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "description": "A formation name in the file."
                },
                "pads": {
                  "type": "integer",
                  "description": "Pads naming it.",
                  "minimum": 1
                }
              },
              "additionalProperties": false
            },
            "description": "Formation names that matched nothing, most pads first."
          },
          "skipped": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A record left out.",
              "required": [
                "index",
                "reason"
              ],
              "properties": {
                "index": {
                  "type": "integer",
                  "description": "Record or feature index in the file.",
                  "minimum": 0
                },
                "reason": {
                  "type": "string",
                  "description": "Why it isn't a pad, as POST /areas gives it."
                }
              },
              "additionalProperties": false
            },
            "description": "Records that aren't areas, as POST /areas lists them."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sentence."
            },
            "description": "What to check: POST /areas' warnings but the one on holes or several parts, points, a role field past the property cap, pads left out or with issues, unknown formations, filled stage fields the model set's models don't read."
          },
          "pads": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PadRead"
            },
            "description": "Every polygon of the file read as an area, in file order."
          },
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WellInput"
            },
            "description": "The kept pads' wells, pad by pad, then in fill order: shl, bhl, formation and pad, ready to post as wells to POST /plans."
          },
          "pad_values": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PadInput"
            },
            "description": "A PadInput for each kept pad, with its TIL date, completions and landing when the file gives them, ready to post as pads to POST /plans with wells."
          }
        },
        "additionalProperties": false
      },
      "WellsSearchRequest": {
        "type": "object",
        "description": "A unit scope, and GET /wells' filters. Send area or polygon, not both, or outlines.",
        "required": [],
        "properties": {
          "area": {
            "$ref": "#/components/schemas/UnitArea",
            "description": "The unit as a GeoJSON Polygon or MultiPolygon in WGS 84, with only type and coordinates: an area's geometry from POST /areas. Rings may wind either way and need not repeat their first point; holes are left out. Not with polygon. A hole that isn't inside its outline is a 400 on that ring. Holes are checked in order up to a fixed amount of checking per request; past it a hole is taken as sent."
          },
          "polygon": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LngLat"
            },
            "description": "The unit as one ring of corners, in order (closing point optional): an area's fill.polygon, or what POST /layouts/fill takes. Not with area. Edges that cross are a 400, tested on rings of up to 500 corners.",
            "minItems": 3,
            "maxItems": 200001
          },
          "buffer_ft": {
            "type": "number",
            "description": "Also take wells within this many feet of the area (0 takes only those inside).",
            "minimum": 0,
            "maximum": 5280,
            "default": 0
          },
          "match": {
            "type": "string",
            "description": "midpoint: a well is in by its lateral midpoint; lateral: also by any part of its lateral, heel (else surface hole) to bottom hole.",
            "enum": [
              "midpoint",
              "lateral"
            ],
            "default": "midpoint"
          },
          "outlines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UnitOutline"
            },
            "description": "Several outlines instead of one scope: each its own area or polygon with its own buffer_ft and match. A well is kept when it is in every outline without exclude and in none with exclude: true; at least one must be without exclude. Not with area, polygon, buffer_ft or match.",
            "minItems": 1,
            "maxItems": 10
          },
          "keys": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A wellbore key.",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "Only these wells: wellbore keys, exact, such as `SB329-01414`, at most 50 distinct (a repeat counts once). Combines with the unit and every other filter.\n\nA key the dataset lacks matches nothing rather than failing. Past the cap is a 400 naming `keys` with `details.max` and `details.count`; an empty array is a 400 (leave `keys` out for every well).",
            "minItems": 1
          },
          "formation": {
            "type": [
              "string",
              "array"
            ],
            "items": {
              "type": "string",
              "maxLength": 100
            },
            "maxItems": 50,
            "description": "Only these formations: a name, names separated by commas, or an array of names, case-insensitive."
          },
          "q": {
            "type": "string",
            "description": "Only wells whose name or wellbore key contains this text, ignoring case.",
            "maxLength": 100
          },
          "operator": {
            "type": "string",
            "description": "Only wells whose operator contains this text, ignoring case.",
            "maxLength": 100
          },
          "fields": {
            "type": [
              "string",
              "array"
            ],
            "items": {
              "type": "string",
              "maxLength": 100
            },
            "maxItems": 50,
            "description": "Only these columns or properties, and area_distance_ft; wellbore_key is always there. A name, names separated by commas, or an array.\n\nFormat columns: `wellbore_key`, `well_name`, `operator`, `formation`, `mid_lon`, `mid_lat`, `shl_lon`, `shl_lat`, `heel_lon`, `heel_lat`, `bhl_lon`, `bhl_lat`, `cum_boe_12`, `first_year`. Format geojson: `wellbore_key`, `well_name`, `operator`, `formation`, `first_prod`, `lateral_length`, `tvd_td`, `cum_boe_12`, `shl_lon`, `shl_lat`, `heel_lon`, `heel_lat`, `bhl_lon`, `bhl_lat`.\n\nEither format also takes `basin`, `subbasin`, `state`, `county`, `lateral_length`, `tvd_td`, `lat`, `lon`, `first_prod`, `last_prod`, `cum_oil_12`, `cum_gas_12`, `cum_boe_12`, `cum_oil_life`, `cum_gas_life`, `cum_boe_life`, `total_proppant`, `total_fluid`, `stage_count`, `frac_date`, `til_date`, `first_year`, `fluid_bbl_per_ft`, `proppant_lb_per_ft`, `cum_boe_12_per_1000_ft`, `cum_oil_12_per_1000_ft`, `cum_gas_12_per_1000_ft`.\n\nThese are GET /wells/{key}'s header fields, `first_year`, per-ft completions, and 12-month BOE, oil (bbl) and gas (mcf) per 1,000 ft of lateral, after the default fields in that order.\n\nCoordinates are rounded to 5 decimals, volumes to whole units, per-ft values to 0.1, and dates are YYYY-MM-DD. `lat` and `lon` are the header's point; the map uses `mid_lon` and `mid_lat`."
          },
          "format": {
            "type": "string",
            "description": "Response layout, as GET /wells: every well as parallel arrays, or a page of GeoJSON Points.",
            "enum": [
              "columns",
              "geojson"
            ],
            "default": "columns"
          },
          "limit": {
            "type": "integer",
            "description": "The page size: format geojson 1 to 1,000 (default 100); format columns 1 to 10,000, which adds next_cursor, and every well in scope without it.",
            "minimum": 1,
            "maximum": 10000,
            "default": 100
          },
          "cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "next_cursor from the previous page, with the same body, in either format."
          },
          "sort": {
            "type": "string",
            "description": "Order the wells by this field instead of inside first, then nearest: any name `fields` takes except the coordinates and the distances. Wells without a value come last in either order; ties go by wellbore key, so `cursor` pages are stable. An unknown name is a 400 with `details.allowed`.",
            "enum": [
              "wellbore_key",
              "well_name",
              "operator",
              "formation",
              "cum_boe_12",
              "first_year",
              "first_prod",
              "lateral_length",
              "tvd_td",
              "basin",
              "subbasin",
              "state",
              "county",
              "last_prod",
              "cum_oil_12",
              "cum_gas_12",
              "cum_oil_life",
              "cum_gas_life",
              "cum_boe_life",
              "total_proppant",
              "total_fluid",
              "stage_count",
              "frac_date",
              "til_date",
              "fluid_bbl_per_ft",
              "proppant_lb_per_ft",
              "cum_boe_12_per_1000_ft",
              "cum_oil_12_per_1000_ft",
              "cum_gas_12_per_1000_ft"
            ]
          },
          "order": {
            "type": "string",
            "description": "With `sort` (ignored without it): `desc`, largest or latest first, or `asc`.",
            "enum": [
              "asc",
              "desc"
            ],
            "default": "desc"
          },
          "county": {
            "type": [
              "string",
              "array"
            ],
            "items": {
              "type": "string",
              "maxLength": 100
            },
            "maxItems": 50,
            "description": "Only wells in these counties: exact names, case-insensitive; a name, names separated by commas, or an array of at most 50."
          },
          "operators": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "An exact operator name, case-insensitive.",
              "maxLength": 100
            },
            "description": "Only wells of these operators, at most 50; operator stays a substring match.",
            "maxItems": 50
          },
          "lateral_length_min": {
            "type": "number",
            "description": "Only wells whose `lateral_length` is at least this, in ft."
          },
          "lateral_length_max": {
            "type": "number",
            "description": "Only wells whose `lateral_length` is at most this, in ft."
          },
          "tvd_td_min": {
            "type": "number",
            "description": "Only wells whose `tvd_td` is at least this, in ft."
          },
          "tvd_td_max": {
            "type": "number",
            "description": "Only wells whose `tvd_td` is at most this, in ft."
          },
          "cum_oil_12_min": {
            "type": "number",
            "description": "Only wells whose `cum_oil_12` is at least this, in bbl."
          },
          "cum_oil_12_max": {
            "type": "number",
            "description": "Only wells whose `cum_oil_12` is at most this, in bbl."
          },
          "cum_gas_12_min": {
            "type": "number",
            "description": "Only wells whose `cum_gas_12` is at least this, in mcf."
          },
          "cum_gas_12_max": {
            "type": "number",
            "description": "Only wells whose `cum_gas_12` is at most this, in mcf."
          },
          "cum_boe_12_min": {
            "type": "number",
            "description": "Only wells whose `cum_boe_12` is at least this, in BOE."
          },
          "cum_boe_12_max": {
            "type": "number",
            "description": "Only wells whose `cum_boe_12` is at most this, in BOE."
          },
          "cum_oil_life_min": {
            "type": "number",
            "description": "Only wells whose `cum_oil_life` is at least this, in bbl."
          },
          "cum_oil_life_max": {
            "type": "number",
            "description": "Only wells whose `cum_oil_life` is at most this, in bbl."
          },
          "cum_gas_life_min": {
            "type": "number",
            "description": "Only wells whose `cum_gas_life` is at least this, in mcf."
          },
          "cum_gas_life_max": {
            "type": "number",
            "description": "Only wells whose `cum_gas_life` is at most this, in mcf."
          },
          "cum_boe_life_min": {
            "type": "number",
            "description": "Only wells whose `cum_boe_life` is at least this, in BOE."
          },
          "cum_boe_life_max": {
            "type": "number",
            "description": "Only wells whose `cum_boe_life` is at most this, in BOE."
          },
          "total_proppant_min": {
            "type": "number",
            "description": "Only wells whose `total_proppant` is at least this, in lb."
          },
          "total_proppant_max": {
            "type": "number",
            "description": "Only wells whose `total_proppant` is at most this, in lb."
          },
          "total_fluid_min": {
            "type": "number",
            "description": "Only wells whose `total_fluid` is at least this, in bbl."
          },
          "total_fluid_max": {
            "type": "number",
            "description": "Only wells whose `total_fluid` is at most this, in bbl."
          },
          "stage_count_min": {
            "type": "number",
            "description": "Only wells whose `stage_count` is at least this, in stages."
          },
          "stage_count_max": {
            "type": "number",
            "description": "Only wells whose `stage_count` is at most this, in stages."
          },
          "first_year_min": {
            "type": "number",
            "description": "Only wells whose `first_year` is at least this, in years."
          },
          "first_year_max": {
            "type": "number",
            "description": "Only wells whose `first_year` is at most this, in years."
          },
          "fluid_bbl_per_ft_min": {
            "type": "number",
            "description": "Only wells whose `fluid_bbl_per_ft` is at least this, in bbl/ft."
          },
          "fluid_bbl_per_ft_max": {
            "type": "number",
            "description": "Only wells whose `fluid_bbl_per_ft` is at most this, in bbl/ft."
          },
          "proppant_lb_per_ft_min": {
            "type": "number",
            "description": "Only wells whose `proppant_lb_per_ft` is at least this, in lb/ft."
          },
          "proppant_lb_per_ft_max": {
            "type": "number",
            "description": "Only wells whose `proppant_lb_per_ft` is at most this, in lb/ft."
          },
          "cum_boe_12_per_1000_ft_min": {
            "type": "number",
            "description": "Only wells whose `cum_boe_12_per_1000_ft` is at least this, in BOE per 1,000 ft of lateral."
          },
          "cum_boe_12_per_1000_ft_max": {
            "type": "number",
            "description": "Only wells whose `cum_boe_12_per_1000_ft` is at most this, in BOE per 1,000 ft of lateral."
          },
          "cum_oil_12_per_1000_ft_min": {
            "type": "number",
            "description": "Only wells whose `cum_oil_12_per_1000_ft` is at least this, in bbl per 1,000 ft of lateral."
          },
          "cum_oil_12_per_1000_ft_max": {
            "type": "number",
            "description": "Only wells whose `cum_oil_12_per_1000_ft` is at most this, in bbl per 1,000 ft of lateral."
          },
          "cum_gas_12_per_1000_ft_min": {
            "type": "number",
            "description": "Only wells whose `cum_gas_12_per_1000_ft` is at least this, in mcf per 1,000 ft of lateral."
          },
          "cum_gas_12_per_1000_ft_max": {
            "type": "number",
            "description": "Only wells whose `cum_gas_12_per_1000_ft` is at most this, in mcf per 1,000 ft of lateral."
          },
          "first_prod_min": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `first_prod` is on or after this day, YYYY-MM-DD."
          },
          "first_prod_max": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `first_prod` is on or before this day, YYYY-MM-DD."
          },
          "last_prod_min": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `last_prod` is on or after this day, YYYY-MM-DD."
          },
          "last_prod_max": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `last_prod` is on or before this day, YYYY-MM-DD."
          },
          "frac_date_min": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `frac_date` is on or after this day, YYYY-MM-DD."
          },
          "frac_date_max": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `frac_date` is on or before this day, YYYY-MM-DD."
          },
          "til_date_min": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `til_date` is on or after this day, YYYY-MM-DD."
          },
          "til_date_max": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `til_date` is on or before this day, YYYY-MM-DD."
          }
        },
        "additionalProperties": false,
        "allOf": [
          {
            "oneOf": [
              {
                "required": [
                  "area"
                ],
                "properties": {
                  "area": true
                }
              },
              {
                "required": [
                  "polygon"
                ],
                "properties": {
                  "polygon": true
                }
              },
              {
                "required": [
                  "outlines"
                ],
                "properties": {
                  "outlines": true
                }
              }
            ]
          },
          {
            "not": {
              "required": [
                "outlines"
              ],
              "properties": {
                "outlines": true
              },
              "anyOf": [
                {
                  "required": [
                    "buffer_ft"
                  ],
                  "properties": {
                    "buffer_ft": true
                  }
                },
                {
                  "required": [
                    "match"
                  ],
                  "properties": {
                    "match": true
                  }
                }
              ]
            }
          }
        ]
      },
      "UnitSummaryRequest": {
        "type": "object",
        "description": "A unit scope. Send area or polygon, not both.",
        "required": [],
        "properties": {
          "area": {
            "$ref": "#/components/schemas/UnitArea",
            "description": "The unit as a GeoJSON Polygon or MultiPolygon in WGS 84, with only type and coordinates: an area's geometry from POST /areas. Rings may wind either way and need not repeat their first point; holes are left out. Not with polygon. A hole that isn't inside its outline is a 400 on that ring. Holes are checked in order up to a fixed amount of checking per request; past it a hole is taken as sent."
          },
          "polygon": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LngLat"
            },
            "description": "The unit as one ring of corners, in order (closing point optional): an area's fill.polygon, or what POST /layouts/fill takes. Not with area. Edges that cross are a 400, tested on rings of up to 500 corners.",
            "minItems": 3,
            "maxItems": 200001
          },
          "buffer_ft": {
            "type": "number",
            "description": "Also take wells within this many feet of the area (0 takes only those inside).",
            "minimum": 0,
            "maximum": 5280,
            "default": 0
          },
          "match": {
            "type": "string",
            "description": "midpoint: a well is in by its lateral midpoint; lateral: also by any part of its lateral, heel (else surface hole) to bottom hole.",
            "enum": [
              "midpoint",
              "lateral"
            ],
            "default": "midpoint"
          },
          "formation": {
            "type": [
              "string",
              "array"
            ],
            "items": {
              "type": "string",
              "maxLength": 100
            },
            "maxItems": 50,
            "description": "Only these formations' wells, formations and completions: a name, names separated by commas, or an array of names, case-insensitive."
          }
        },
        "additionalProperties": false,
        "oneOf": [
          {
            "required": [
              "area"
            ],
            "properties": {
              "area": true
            }
          },
          {
            "required": [
              "polygon"
            ],
            "properties": {
              "polygon": true
            }
          }
        ]
      },
      "UnitOutline": {
        "type": "object",
        "description": "One of POST /wells/search outlines: area or polygon, not both, with its own buffer_ft and match.",
        "required": [],
        "properties": {
          "area": {
            "$ref": "#/components/schemas/UnitArea",
            "description": "The unit as a GeoJSON Polygon or MultiPolygon in WGS 84, with only type and coordinates: an area's geometry from POST /areas. Rings may wind either way and need not repeat their first point; holes are left out. Not with polygon. A hole that isn't inside its outline is a 400 on that ring. Holes are checked in order up to a fixed amount of checking per request; past it a hole is taken as sent."
          },
          "polygon": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LngLat"
            },
            "description": "The unit as one ring of corners, in order (closing point optional): an area's fill.polygon, or what POST /layouts/fill takes. Not with area. Edges that cross are a 400, tested on rings of up to 500 corners.",
            "minItems": 3,
            "maxItems": 200001
          },
          "buffer_ft": {
            "type": "number",
            "description": "Also take wells within this many feet of the area (0 takes only those inside).",
            "minimum": 0,
            "maximum": 5280,
            "default": 0
          },
          "match": {
            "type": "string",
            "description": "midpoint: a well is in by its lateral midpoint; lateral: also by any part of its lateral, heel (else surface hole) to bottom hole.",
            "enum": [
              "midpoint",
              "lateral"
            ],
            "default": "midpoint"
          },
          "exclude": {
            "type": "boolean",
            "description": "true: leave out the wells in this outline, by its own match and buffer_ft. Absent or false: keep only the wells in it.",
            "default": false
          }
        },
        "additionalProperties": false,
        "oneOf": [
          {
            "required": [
              "area"
            ],
            "properties": {
              "area": true
            }
          },
          {
            "required": [
              "polygon"
            ],
            "properties": {
              "polygon": true
            }
          }
        ]
      },
      "UnitArea": {
        "description": "A unit in WGS 84, with only type and coordinates: an area's geometry from POST /areas, or your own.",
        "oneOf": [
          {
            "type": "object",
            "description": "A polygon.",
            "required": [
              "type",
              "coordinates"
            ],
            "properties": {
              "type": {
                "const": "Polygon",
                "description": "One part."
              },
              "coordinates": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/LngLat"
                  },
                  "description": "A ring: 3 or more corners, in order, either way round; a closing point is optional.",
                  "minItems": 3
                },
                "description": "The outer ring, then its holes.",
                "minItems": 1
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "A multipolygon.",
            "required": [
              "type",
              "coordinates"
            ],
            "properties": {
              "type": {
                "const": "MultiPolygon",
                "description": "Several parts, taken together."
              },
              "coordinates": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/LngLat"
                    },
                    "description": "A ring: 3 or more corners, in order, either way round; a closing point is optional.",
                    "minItems": 3
                  },
                  "description": "A part: its outer ring, then its holes.",
                  "minItems": 1
                },
                "description": "The parts.",
                "minItems": 1
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "UnitGridStats": {
        "type": "object",
        "description": "One grid over the cells inside the area.",
        "required": [
          "feature_name",
          "unit",
          "cells",
          "sampled",
          "min",
          "median",
          "max"
        ],
        "properties": {
          "feature_name": {
            "type": "string",
            "description": "The grid, as GET /subsurface/grids/{feature_name} names it."
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "ft, fraction, or null when unknown."
          },
          "cells": {
            "type": "integer",
            "description": "Grid cells inside the area with a value, after any sampling.",
            "minimum": 1
          },
          "sampled": {
            "type": "boolean",
            "description": "True when a coarser lattice was used (more cells than the cap lie in the area's bbox)."
          },
          "min": {
            "type": "number",
            "description": "Smallest value, 5 significant digits."
          },
          "median": {
            "type": "number",
            "description": "Median value."
          },
          "max": {
            "type": "number",
            "description": "Largest value."
          }
        },
        "additionalProperties": false
      },
      "UnitSummary": {
        "type": "object",
        "description": "What a unit holds.",
        "required": [
          "area",
          "wells",
          "formations",
          "completions",
          "warnings"
        ],
        "properties": {
          "area": {
            "type": "object",
            "description": "The area, measured as POST /areas measures it.",
            "required": [
              "acres",
              "long_axis_azimuth_deg",
              "bbox",
              "in_dataset"
            ],
            "properties": {
              "acres": {
                "type": "number",
                "description": "Area, acres, holes taken out."
              },
              "long_axis_azimuth_deg": {
                "type": "integer",
                "description": "The bearing of the largest part's longest edge, degrees from north, -90 to 90, as POST /areas reports it.",
                "minimum": -90,
                "maximum": 90
              },
              "bbox": {
                "type": "array",
                "items": {
                  "type": "number",
                  "description": "Degrees."
                },
                "description": "[west, south, east, north] of the outer rings.",
                "minItems": 4,
                "maxItems": 4
              },
              "in_dataset": {
                "type": "boolean",
                "description": "True when the bbox meets the dataset's (GET /dataset bbox)."
              }
            },
            "additionalProperties": false
          },
          "wells": {
            "type": "object",
            "description": "The wells in scope (inside and buffer together, unless counted apart).",
            "required": [
              "inside",
              "buffer",
              "by_formation",
              "by_operator",
              "by_first_year"
            ],
            "properties": {
              "inside": {
                "type": "integer",
                "description": "Wells in scope inside the area.",
                "minimum": 0
              },
              "buffer": {
                "type": "integer",
                "description": "Wells in scope outside the area, within buffer_ft.",
                "minimum": 0
              },
              "by_formation": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "One formation's wells.",
                  "required": [
                    "formation",
                    "wells",
                    "inside",
                    "median_lateral_ft",
                    "median_tvd_ft",
                    "median_cum_boe_12",
                    "total_cum_boe_12",
                    "median_cum_boe_12_per_1000_ft",
                    "first_prod_earliest",
                    "first_prod_latest"
                  ],
                  "properties": {
                    "formation": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Formation, or null for wells without one."
                    },
                    "wells": {
                      "type": "integer",
                      "description": "Wells in scope: inside and within buffer_ft.",
                      "minimum": 1
                    },
                    "inside": {
                      "type": "integer",
                      "description": "Of them, those inside the area (not in the buffer).",
                      "minimum": 0
                    },
                    "median_lateral_ft": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Median lateral length, ft."
                    },
                    "median_tvd_ft": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Median TVD, ft."
                    },
                    "median_cum_boe_12": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Median first 12 months of production, BOE."
                    },
                    "total_cum_boe_12": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Their first 12 months of production added up, BOE."
                    },
                    "median_cum_boe_12_per_1000_ft": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Median of each well's 12-month BOE per 1,000 ft of lateral, BOE."
                    },
                    "first_prod_earliest": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Earliest first production.",
                      "format": "date"
                    },
                    "first_prod_latest": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Latest first production.",
                      "format": "date"
                    }
                  },
                  "additionalProperties": false
                },
                "description": "By formation, top to bottom; wells without one last."
              },
              "by_operator": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "One operator's wells.",
                  "required": [
                    "operator",
                    "wells"
                  ],
                  "properties": {
                    "operator": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Operator, Other on the last row when there are more, or null for wells without one."
                    },
                    "wells": {
                      "type": "integer",
                      "description": "Wells in scope.",
                      "minimum": 1
                    },
                    "others": {
                      "type": "integer",
                      "description": "On the Other row only: how many operators it sums.",
                      "minimum": 1
                    }
                  },
                  "additionalProperties": false
                },
                "description": "The 10 operators with the most wells (ties by name), then Other."
              },
              "by_first_year": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "One year's wells.",
                  "required": [
                    "year",
                    "wells"
                  ],
                  "properties": {
                    "year": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Year of first production, or null."
                    },
                    "wells": {
                      "type": "integer",
                      "description": "Wells in scope.",
                      "minimum": 1
                    }
                  },
                  "additionalProperties": false
                },
                "description": "By year, oldest first; wells without one last."
              }
            },
            "additionalProperties": false
          },
          "formations": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A formation.",
              "required": [
                "formation",
                "label",
                "wells",
                "inside",
                "has_grids",
                "grids"
              ],
              "properties": {
                "formation": {
                  "type": "string",
                  "description": "Formation."
                },
                "label": {
                  "type": "string",
                  "description": "Display name."
                },
                "wells": {
                  "type": "integer",
                  "description": "Wells in scope landed in it: inside and within buffer_ft.",
                  "minimum": 0
                },
                "inside": {
                  "type": "integer",
                  "description": "Of them, those inside the area (not in the buffer).",
                  "minimum": 0
                },
                "has_grids": {
                  "type": "boolean",
                  "description": "True when it has subsurface grids."
                },
                "grids": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "additionalProperties": {
                    "anyOf": [
                      {
                        "$ref": "#/components/schemas/UnitGridStats"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "description": "By rock property (novi_structuraldepth, novi_thickness_avg, ...): the grid over the cells inside the area, or null when it has none there. Null without grids or with no cell inside."
                }
              },
              "additionalProperties": false
            },
            "description": "Every formation, top to bottom (only the asked ones with formation)."
          },
          "completions": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One formation's completions.",
              "required": [
                "formation",
                "fluid_bbl_per_ft",
                "proppant_lb_per_ft",
                "wells"
              ],
              "properties": {
                "formation": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Formation, or null."
                },
                "fluid_bbl_per_ft": {
                  "type": "number",
                  "description": "Median fluid, bbl/ft, to 0.1."
                },
                "proppant_lb_per_ft": {
                  "type": "number",
                  "description": "Median proppant, lb/ft, to 1."
                },
                "wells": {
                  "type": "integer",
                  "description": "In-scope wells with both.",
                  "minimum": 1
                }
              },
              "additionalProperties": false
            },
            "description": "By formation, top to bottom; empty when no in-scope well has completions."
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A sentence."
            },
            "description": "What to check: nothing inside, the area off the dataset, the grids unavailable."
          }
        },
        "additionalProperties": false
      },
      "WellFacets": {
        "type": "object",
        "description": "Counts of wells by value.",
        "required": [
          "wells",
          "facets"
        ],
        "properties": {
          "wells": {
            "type": "integer",
            "description": "Wells matching every filter, each facet's own included: not disjunctive.",
            "minimum": 0
          },
          "facets": {
            "type": "object",
            "additionalProperties": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/TextFacet"
                },
                {
                  "$ref": "#/components/schemas/NumberFacet"
                }
              ]
            },
            "description": "Each asked facet by its name, in the order asked; counted without its own exact filter.\n\nNames: `operator`, `formation`, `county`, `subbasin`, `state`, `basin`, `first_year`, `lateral_length`, `tvd_td`, `cum_boe_12`, `cum_oil_12`, `cum_gas_12`, `cum_boe_life`, `stage_count`, `fluid_bbl_per_ft`, `proppant_lb_per_ft`, `cum_boe_12_per_1000_ft`, `cum_oil_12_per_1000_ft`, `cum_gas_12_per_1000_ft`."
          }
        },
        "additionalProperties": false
      },
      "TextFacet": {
        "type": "object",
        "description": "A text facet: values and their well counts.",
        "required": [
          "type",
          "distinct",
          "missing",
          "values",
          "others"
        ],
        "properties": {
          "type": {
            "const": "text",
            "description": "A text field."
          },
          "distinct": {
            "type": "integer",
            "description": "Values matching contains, or every value without it.",
            "minimum": 0
          },
          "missing": {
            "type": "integer",
            "description": "Wells counted without a value.",
            "minimum": 0
          },
          "values": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A value.",
              "required": [
                "value",
                "wells"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "description": "The value, as stored."
                },
                "wells": {
                  "type": "integer",
                  "description": "Wells with it.",
                  "minimum": 1
                }
              },
              "additionalProperties": false
            },
            "description": "Up to limit values: with contains, those with a word starting with it first; then most wells first, then by name."
          },
          "others": {
            "anyOf": [
              {
                "type": "object",
                "description": "The values past limit, summed.",
                "required": [
                  "values",
                  "wells"
                ],
                "properties": {
                  "values": {
                    "type": "integer",
                    "description": "Values left out.",
                    "minimum": 1
                  },
                  "wells": {
                    "type": "integer",
                    "description": "Their wells.",
                    "minimum": 1
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The values past limit, summed; null when none is left out."
          }
        },
        "additionalProperties": false
      },
      "NumberFacet": {
        "type": "object",
        "description": "A numeric facet: its spread across wells.",
        "required": [
          "type",
          "unit",
          "wells",
          "missing",
          "min",
          "max",
          "quantiles",
          "histogram"
        ],
        "properties": {
          "type": {
            "const": "number",
            "description": "A numeric field."
          },
          "unit": {
            "type": "string",
            "description": "Unit of the values: ft, bbl, mcf, BOE, bbl/ft, lb/ft, BOE per 1,000 ft, stages or year."
          },
          "wells": {
            "type": "integer",
            "description": "Wells counted with a value.",
            "minimum": 0
          },
          "missing": {
            "type": "integer",
            "description": "Wells counted without one.",
            "minimum": 0
          },
          "min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Smallest value; null when none has one."
          },
          "max": {
            "type": [
              "number",
              "null"
            ],
            "description": "Largest value; null when none has one."
          },
          "quantiles": {
            "type": "object",
            "description": "Quantiles across wells, type 7, to 0.1; not P-level bands.",
            "required": [
              "q10",
              "q50",
              "q90"
            ],
            "properties": {
              "q10": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "10th-percentile well, the low end."
              },
              "q50": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Median well."
              },
              "q90": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "90th-percentile well, the high end."
              }
            },
            "additionalProperties": false
          },
          "histogram": {
            "type": "object",
            "description": "Bins of equal width from min to max, counted against the rounded edges shown (the outer two rounded outward), the last closed; a whole-number field's bins are a whole number of values wide and may be fewer than bins.",
            "required": [
              "edges",
              "counts"
            ],
            "properties": {
              "edges": {
                "type": "array",
                "items": {
                  "type": "number",
                  "description": "A bin edge."
                },
                "description": "Bin edges, one more than counts, to 0.1 or finer where 0.1 would repeat an edge, strictly ascending except a single value's two equal edges; for a whole-number field, half steps between whole values; empty when no well has a value."
              },
              "counts": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "description": "Wells in the bin.",
                  "minimum": 0
                },
                "description": "Wells per bin; they add up to wells."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "TypeCurveRequest": {
        "type": "object",
        "description": "Which existing wells, and what to compute. Every key is optional and the filters combine; send area or polygon, not both, and neither with bbox or near.",
        "required": [],
        "properties": {
          "wells": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A wellbore key.",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "Only these wells, 1 to 1,000; a repeat counts once, and a key the dataset lacks is a 400 naming the first (`details.key`). A key's well without a location is used unless bbox, near or a unit is sent; then it counts in excluded.no_location.",
            "minItems": 1,
            "maxItems": 1000
          },
          "formation": {
            "type": [
              "string",
              "array"
            ],
            "items": {
              "type": "string",
              "maxLength": 100
            },
            "maxItems": 50,
            "description": "Only these formations: a name, names separated by commas, or an array of names, case-insensitive."
          },
          "q": {
            "type": "string",
            "description": "Only wells whose name or wellbore key contains this text, ignoring case.",
            "maxLength": 100
          },
          "operator": {
            "type": "string",
            "description": "Only wells whose operator contains this text, ignoring case.",
            "maxLength": 100
          },
          "operators": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "An exact operator name, case-insensitive.",
              "maxLength": 100
            },
            "description": "Only wells of these operators, at most 50.",
            "maxItems": 50
          },
          "county": {
            "type": [
              "string",
              "array"
            ],
            "items": {
              "type": "string",
              "maxLength": 100
            },
            "maxItems": 50,
            "description": "Only wells in these counties: exact names, case-insensitive; a name, names separated by commas, or an array of at most 50."
          },
          "lateral_length_min": {
            "type": "number",
            "description": "Only wells whose `lateral_length` is at least this, in ft."
          },
          "lateral_length_max": {
            "type": "number",
            "description": "Only wells whose `lateral_length` is at most this, in ft."
          },
          "tvd_td_min": {
            "type": "number",
            "description": "Only wells whose `tvd_td` is at least this, in ft."
          },
          "tvd_td_max": {
            "type": "number",
            "description": "Only wells whose `tvd_td` is at most this, in ft."
          },
          "cum_oil_12_min": {
            "type": "number",
            "description": "Only wells whose `cum_oil_12` is at least this, in bbl."
          },
          "cum_oil_12_max": {
            "type": "number",
            "description": "Only wells whose `cum_oil_12` is at most this, in bbl."
          },
          "cum_gas_12_min": {
            "type": "number",
            "description": "Only wells whose `cum_gas_12` is at least this, in mcf."
          },
          "cum_gas_12_max": {
            "type": "number",
            "description": "Only wells whose `cum_gas_12` is at most this, in mcf."
          },
          "cum_boe_12_min": {
            "type": "number",
            "description": "Only wells whose `cum_boe_12` is at least this, in BOE."
          },
          "cum_boe_12_max": {
            "type": "number",
            "description": "Only wells whose `cum_boe_12` is at most this, in BOE."
          },
          "cum_oil_life_min": {
            "type": "number",
            "description": "Only wells whose `cum_oil_life` is at least this, in bbl."
          },
          "cum_oil_life_max": {
            "type": "number",
            "description": "Only wells whose `cum_oil_life` is at most this, in bbl."
          },
          "cum_gas_life_min": {
            "type": "number",
            "description": "Only wells whose `cum_gas_life` is at least this, in mcf."
          },
          "cum_gas_life_max": {
            "type": "number",
            "description": "Only wells whose `cum_gas_life` is at most this, in mcf."
          },
          "cum_boe_life_min": {
            "type": "number",
            "description": "Only wells whose `cum_boe_life` is at least this, in BOE."
          },
          "cum_boe_life_max": {
            "type": "number",
            "description": "Only wells whose `cum_boe_life` is at most this, in BOE."
          },
          "total_proppant_min": {
            "type": "number",
            "description": "Only wells whose `total_proppant` is at least this, in lb."
          },
          "total_proppant_max": {
            "type": "number",
            "description": "Only wells whose `total_proppant` is at most this, in lb."
          },
          "total_fluid_min": {
            "type": "number",
            "description": "Only wells whose `total_fluid` is at least this, in bbl."
          },
          "total_fluid_max": {
            "type": "number",
            "description": "Only wells whose `total_fluid` is at most this, in bbl."
          },
          "stage_count_min": {
            "type": "number",
            "description": "Only wells whose `stage_count` is at least this, in stages."
          },
          "stage_count_max": {
            "type": "number",
            "description": "Only wells whose `stage_count` is at most this, in stages."
          },
          "first_year_min": {
            "type": "number",
            "description": "Only wells whose `first_year` is at least this, in years."
          },
          "first_year_max": {
            "type": "number",
            "description": "Only wells whose `first_year` is at most this, in years."
          },
          "fluid_bbl_per_ft_min": {
            "type": "number",
            "description": "Only wells whose `fluid_bbl_per_ft` is at least this, in bbl/ft."
          },
          "fluid_bbl_per_ft_max": {
            "type": "number",
            "description": "Only wells whose `fluid_bbl_per_ft` is at most this, in bbl/ft."
          },
          "proppant_lb_per_ft_min": {
            "type": "number",
            "description": "Only wells whose `proppant_lb_per_ft` is at least this, in lb/ft."
          },
          "proppant_lb_per_ft_max": {
            "type": "number",
            "description": "Only wells whose `proppant_lb_per_ft` is at most this, in lb/ft."
          },
          "cum_boe_12_per_1000_ft_min": {
            "type": "number",
            "description": "Only wells whose `cum_boe_12_per_1000_ft` is at least this, in BOE per 1,000 ft of lateral."
          },
          "cum_boe_12_per_1000_ft_max": {
            "type": "number",
            "description": "Only wells whose `cum_boe_12_per_1000_ft` is at most this, in BOE per 1,000 ft of lateral."
          },
          "cum_oil_12_per_1000_ft_min": {
            "type": "number",
            "description": "Only wells whose `cum_oil_12_per_1000_ft` is at least this, in bbl per 1,000 ft of lateral."
          },
          "cum_oil_12_per_1000_ft_max": {
            "type": "number",
            "description": "Only wells whose `cum_oil_12_per_1000_ft` is at most this, in bbl per 1,000 ft of lateral."
          },
          "cum_gas_12_per_1000_ft_min": {
            "type": "number",
            "description": "Only wells whose `cum_gas_12_per_1000_ft` is at least this, in mcf per 1,000 ft of lateral."
          },
          "cum_gas_12_per_1000_ft_max": {
            "type": "number",
            "description": "Only wells whose `cum_gas_12_per_1000_ft` is at most this, in mcf per 1,000 ft of lateral."
          },
          "first_prod_min": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `first_prod` is on or after this day, YYYY-MM-DD."
          },
          "first_prod_max": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `first_prod` is on or before this day, YYYY-MM-DD."
          },
          "last_prod_min": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `last_prod` is on or after this day, YYYY-MM-DD."
          },
          "last_prod_max": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `last_prod` is on or before this day, YYYY-MM-DD."
          },
          "frac_date_min": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `frac_date` is on or after this day, YYYY-MM-DD."
          },
          "frac_date_max": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `frac_date` is on or before this day, YYYY-MM-DD."
          },
          "til_date_min": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `til_date` is on or after this day, YYYY-MM-DD."
          },
          "til_date_max": {
            "type": "string",
            "format": "date",
            "description": "Only wells whose `til_date` is on or before this day, YYYY-MM-DD."
          },
          "area": {
            "$ref": "#/components/schemas/UnitArea",
            "description": "The unit as a GeoJSON Polygon or MultiPolygon in WGS 84, with only type and coordinates: an area's geometry from POST /areas. Rings may wind either way and need not repeat their first point; holes are left out. Not with polygon. A hole that isn't inside its outline is a 400 on that ring. Holes are checked in order up to a fixed amount of checking per request; past it a hole is taken as sent."
          },
          "polygon": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LngLat"
            },
            "description": "The unit as one ring of corners, in order (closing point optional): an area's fill.polygon, or what POST /layouts/fill takes. Not with area. Edges that cross are a 400, tested on rings of up to 500 corners.",
            "minItems": 3,
            "maxItems": 200001
          },
          "buffer_ft": {
            "type": "number",
            "description": "Also take wells within this many feet of the area (0 takes only those inside).",
            "minimum": 0,
            "maximum": 5280,
            "default": 0
          },
          "match": {
            "type": "string",
            "description": "midpoint: a well is in by its lateral midpoint; lateral: also by any part of its lateral, heel (else surface hole) to bottom hole.",
            "enum": [
              "midpoint",
              "lateral"
            ],
            "default": "midpoint"
          },
          "bbox": {
            "type": "array",
            "items": {
              "type": "number",
              "description": "Degrees."
            },
            "description": "Only wells whose lateral midpoint is inside [west, south, east, north]. Not with area or polygon.",
            "minItems": 4,
            "maxItems": 4
          },
          "near": {
            "type": "array",
            "description": "Only wells within radius_mi of this point, [lng, lat], to the lateral midpoint. Not with area or polygon.",
            "prefixItems": [
              {
                "type": "number",
                "description": "Longitude",
                "minimum": -180,
                "maximum": 180
              },
              {
                "type": "number",
                "description": "Latitude",
                "minimum": -90,
                "maximum": 90
              }
            ],
            "minItems": 2,
            "maxItems": 2,
            "items": false
          },
          "radius_mi": {
            "type": "number",
            "description": "With near: how far from it, miles, greater than 0 and at most 100; default 5.",
            "exclusiveMinimum": 0,
            "maximum": 100,
            "default": 5
          },
          "streams": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A stream; boe is oil + gas / 6, for wells with both, or the one of oil and gas a set serves alone (gas / 6).",
              "enum": [
                "oil",
                "gas",
                "water",
                "boe"
              ]
            },
            "description": "Streams to compute; default all four.",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true
          },
          "measures": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "cum: cumulative volume at the ip_day; rate: the average daily rate over the step ending there (1 day, then 29, then 30).",
              "enum": [
                "cum",
                "rate"
              ]
            },
            "description": "Measures; default both.",
            "minItems": 1,
            "maxItems": 2,
            "uniqueItems": true
          },
          "normalize_lateral_ft": {
            "type": "number",
            "description": "Scale each well's volumes and rates to this lateral length: × normalize_lateral_ft / its lateral_length, so 1000 gives per 1,000 ft of lateral and a planned well's length compares others to it. 100 to 20,000.",
            "minimum": 100,
            "maximum": 20000
          },
          "ip_days": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "An ip_day: 1, or a multiple of 30.",
              "minimum": 1,
              "maximum": 7200
            },
            "description": "The ip_days to compute, at most 240 (a repeat counts once in the answer); default every 30 days from 30 to the last ip_day at least min_wells wells reach, up to 7,200 (20 years); with cohort_ip_day, every 30 days from 30 to it, and only multiples of 30 up to it may be sent.",
            "minItems": 1,
            "maxItems": 240
          },
          "quantiles": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "A whole percentile.",
              "minimum": 1,
              "maximum": 99
            },
            "description": "Quantiles across wells: whole percentiles 1 to 99, at most 9 different ones, as 10,25,50,75,90 for a box plot; `quantiles` then holds exactly `q10`, `q25` and so on. Quantiles of wells' values (type 7, q10 the low end), not P-level bands. Default 10, 50 and 90.",
            "minItems": 1,
            "maxItems": 9,
            "uniqueItems": true
          },
          "min_wells": {
            "type": "integer",
            "description": "Fewest wells at an ip_day for its mean and quantiles; below it they are null and the count still shows. An analog overlay sends 1.",
            "minimum": 1,
            "maximum": 1000,
            "default": 5
          },
          "group_by": {
            "type": "string",
            "description": "One curve per formation, operator or first-production year: the 12 with the most wells, the rest counted in groups_left_out.",
            "enum": [
              "formation",
              "operator",
              "first_year"
            ]
          },
          "include": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "wells: each well's own series, as well_series.",
              "enum": [
                "wells"
              ]
            },
            "description": "Extras; wells takes at most 100 wells used (400 past it, with details.max and details.count).",
            "maxItems": 1,
            "uniqueItems": true
          },
          "cohort_ip_day": {
            "type": "integer",
            "description": "A fixed cohort, a multiple of 30: only wells with a value for every asked stream and measure at every 30-day ip_day from 30 to this one, so each series has the same wells there. Wells left out count in excluded.short_history.\n\nip_days then defaults to every 30 days to it; ip_days sent must be multiples of 30 up to it (400 on ip_days).",
            "minimum": 30,
            "maximum": 7200,
            "multipleOf": 30
          },
          "min_lateral_ft": {
            "type": "number",
            "description": "With normalize_lateral_ft only (without it, a 400): leave out wells whose lateral is shorter than this many ft, counted in excluded.short_lateral. 1 to 20,000.",
            "minimum": 1,
            "maximum": 20000
          },
          "exclude_floor": {
            "type": "boolean",
            "default": false,
            "description": "true: leave out wells whose first production is in the dataset's first production month (GET /dataset first_production), unless their til_date is in that month too, counted in excluded.floor. Absent or false: no floor key."
          },
          "pooled": {
            "type": "boolean",
            "default": false,
            "description": "true, with normalize_lateral_ft only (without it, a 400 on pooled): each series also gets pooled, Σ value / Σ lateral × normalize_lateral_ft at each ip_day over the wells reaching it: their per-foot figure taken together, where mean and the quantiles scale each well first. Absent or false: no pooled key."
          }
        },
        "additionalProperties": false
      },
      "TypeCurveSeries": {
        "type": "object",
        "description": "One measure across wells, parallel to ip_days.",
        "required": [
          "wells",
          "mean"
        ],
        "additionalProperties": false,
        "properties": {
          "wells": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "Wells reaching the ip_day.",
              "minimum": 0
            },
            "description": "How many wells reach each ip_day: on POST /wells/typecurve without cohort_ip_day, later ip_days describe fewer, older wells; on GET /plans/{id}/typecurve/{design}, the wells used with a finite value for this stream and measure there."
          },
          "mean": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "The plain mean of the wells' (normalised) values, a cum to 0.1 and a rate to 0.01; null with fewer than min_wells."
            },
            "description": "Means."
          },
          "pooled": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "The wells' summed values over their summed laterals × normalize_lateral_ft, over the wells reaching the ip_day; rounded as mean; null with fewer than min_wells."
            },
            "description": "With pooled: true only."
          }
        },
        "patternProperties": {
          "^q([1-9]|[1-9][0-9])$": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "That quantile across wells, type 7, rounded as mean; null with fewer than min_wells."
            },
            "description": "One per asked quantile, as q10."
          }
        }
      },
      "TypeCurve": {
        "type": "object",
        "description": "One type curve.",
        "required": [
          "group",
          "wells",
          "streams"
        ],
        "properties": {
          "group": {
            "type": [
              "string",
              "integer",
              "null"
            ],
            "description": "The formation, operator or first-production year, or on a plan the pad key; null without group_by, or for the wells without that value."
          },
          "name": {
            "type": "string",
            "description": "On GET /plans/{id}/typecurve/{design} with group_by=pad, the pad's name when the plan gives one in `pads[].name`; absent otherwise. `group` stays the pad key."
          },
          "wells": {
            "type": "integer",
            "description": "Wells in this curve.",
            "minimum": 0
          },
          "streams": {
            "type": "object",
            "description": "The asked streams.",
            "required": [],
            "properties": {
              "oil": {
                "type": "object",
                "description": "oil: the asked measures.",
                "required": [],
                "properties": {
                  "cum": {
                    "$ref": "#/components/schemas/TypeCurveSeries"
                  },
                  "rate": {
                    "$ref": "#/components/schemas/TypeCurveSeries"
                  }
                },
                "additionalProperties": false
              },
              "gas": {
                "type": "object",
                "description": "gas: the asked measures.",
                "required": [],
                "properties": {
                  "cum": {
                    "$ref": "#/components/schemas/TypeCurveSeries"
                  },
                  "rate": {
                    "$ref": "#/components/schemas/TypeCurveSeries"
                  }
                },
                "additionalProperties": false
              },
              "water": {
                "type": "object",
                "description": "water: the asked measures.",
                "required": [],
                "properties": {
                  "cum": {
                    "$ref": "#/components/schemas/TypeCurveSeries"
                  },
                  "rate": {
                    "$ref": "#/components/schemas/TypeCurveSeries"
                  }
                },
                "additionalProperties": false
              },
              "boe": {
                "type": "object",
                "description": "boe: the asked measures.",
                "required": [],
                "properties": {
                  "cum": {
                    "$ref": "#/components/schemas/TypeCurveSeries"
                  },
                  "rate": {
                    "$ref": "#/components/schemas/TypeCurveSeries"
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "TypeCurveResponse": {
        "type": "object",
        "description": "Analog type curves.",
        "required": [
          "wells",
          "used",
          "excluded",
          "normalize_lateral_ft",
          "min_wells",
          "units",
          "ip_days",
          "curves",
          "groups_left_out"
        ],
        "properties": {
          "wells": {
            "type": "integer",
            "description": "Wells matching the scope.",
            "minimum": 0
          },
          "used": {
            "type": "integer",
            "description": "Of them, those used: on POST /wells/typecurve, with production, a lateral when normalizing, and not left out by exclude_floor, min_lateral_ft or cohort_ip_day; on GET /plans/{id}/typecurve/{design}, with a forecast for the design.",
            "minimum": 0
          },
          "excluded": {
            "type": "object",
            "description": "Wells left out, and why: wells is used plus these. floor, short_lateral and short_history are present only with their options and count each well under the first that leaves it out, in that order.",
            "required": [
              "no_production",
              "no_lateral",
              "no_location"
            ],
            "properties": {
              "no_production": {
                "type": "integer",
                "description": "Wells without production.",
                "minimum": 0
              },
              "no_lateral": {
                "type": "integer",
                "description": "With normalize_lateral_ft, wells with production but without a lateral.",
                "minimum": 0
              },
              "no_location": {
                "type": "integer",
                "description": "With bbox, near or a unit: keyed wells (wells) without a location, which no spatial scope can place.",
                "minimum": 0
              },
              "floor": {
                "type": "integer",
                "description": "With exclude_floor: true, wells whose first production is in the dataset's first production month, without a til_date in it.",
                "minimum": 0
              },
              "short_lateral": {
                "type": "integer",
                "description": "With min_lateral_ft, wells with a shorter lateral.",
                "minimum": 0
              },
              "short_history": {
                "type": "integer",
                "description": "With cohort_ip_day, wells without a value for every asked stream and measure at every 30-day ip_day to it.",
                "minimum": 0
              },
              "no_forecast": {
                "type": "integer",
                "description": "GET /plans/{id}/typecurve/{design} only: plan wells without a forecast for the design, as they couldn't be placed or the forecast failed.",
                "minimum": 0
              }
            },
            "additionalProperties": false
          },
          "normalize_lateral_ft": {
            "type": [
              "number",
              "null"
            ],
            "description": "The lateral every well was scaled to, ft; null without normalize_lateral_ft."
          },
          "min_wells": {
            "type": "integer",
            "description": "Fewest wells for a mean and quantiles.",
            "minimum": 1
          },
          "cohort_ip_day": {
            "type": "integer",
            "description": "The cohort_ip_day sent; only with it.",
            "minimum": 30
          },
          "units": {
            "type": "object",
            "description": "Units: bbl, mcf, bbl and BOE, rates per day.",
            "required": [
              "oil",
              "gas",
              "water",
              "boe",
              "rate"
            ],
            "properties": {
              "oil": {
                "type": "string",
                "description": "Oil volumes."
              },
              "gas": {
                "type": "string",
                "description": "Gas volumes."
              },
              "water": {
                "type": "string",
                "description": "Water volumes."
              },
              "boe": {
                "type": "string",
                "description": "BOE volumes."
              },
              "rate": {
                "type": "string",
                "description": "Rates are those units per day."
              }
            },
            "additionalProperties": false
          },
          "ip_days": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "Days since first production."
            },
            "description": "The ip_days every series is parallel to."
          },
          "curves": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TypeCurve"
            },
            "description": "One curve, or with group_by one per group, most wells first; with group_by and no wells used, empty."
          },
          "groups_left_out": {
            "type": "integer",
            "description": "With group_by, the groups past the largest; else 0.",
            "minimum": 0
          },
          "well_series": {
            "$ref": "#/components/schemas/TypeCurveWellSeries",
            "description": "With include: [\"wells\"]: each well's own series."
          }
        },
        "additionalProperties": false
      },
      "TypeCurveWellSeries": {
        "type": "object",
        "description": "Each used well's own series.",
        "required": [
          "wellbore_key",
          "well_name",
          "lateral_length",
          "streams"
        ],
        "properties": {
          "wellbore_key": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Key."
            },
            "description": "The wells used, in key order."
          },
          "well_name": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ],
              "description": "Name."
            },
            "description": "Their names."
          },
          "lateral_length": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ],
              "description": "ft."
            },
            "description": "Their laterals, ft."
          },
          "streams": {
            "type": "object",
            "description": "The asked streams and measures.",
            "required": [],
            "properties": {
              "oil": {
                "type": "object",
                "description": "oil: the asked measures.",
                "required": [],
                "properties": {
                  "cum": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "The (normalised) value at the ip_day, rounded as a curve's mean; null past the well's history."
                      },
                      "description": "One well, parallel to ip_days."
                    },
                    "description": "One per well, in wellbore_key order."
                  },
                  "rate": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "The (normalised) value at the ip_day, rounded as a curve's mean; null past the well's history."
                      },
                      "description": "One well, parallel to ip_days."
                    },
                    "description": "One per well, in wellbore_key order."
                  }
                },
                "additionalProperties": false
              },
              "gas": {
                "type": "object",
                "description": "gas: the asked measures.",
                "required": [],
                "properties": {
                  "cum": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "The (normalised) value at the ip_day, rounded as a curve's mean; null past the well's history."
                      },
                      "description": "One well, parallel to ip_days."
                    },
                    "description": "One per well, in wellbore_key order."
                  },
                  "rate": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "The (normalised) value at the ip_day, rounded as a curve's mean; null past the well's history."
                      },
                      "description": "One well, parallel to ip_days."
                    },
                    "description": "One per well, in wellbore_key order."
                  }
                },
                "additionalProperties": false
              },
              "water": {
                "type": "object",
                "description": "water: the asked measures.",
                "required": [],
                "properties": {
                  "cum": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "The (normalised) value at the ip_day, rounded as a curve's mean; null past the well's history."
                      },
                      "description": "One well, parallel to ip_days."
                    },
                    "description": "One per well, in wellbore_key order."
                  },
                  "rate": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "The (normalised) value at the ip_day, rounded as a curve's mean; null past the well's history."
                      },
                      "description": "One well, parallel to ip_days."
                    },
                    "description": "One per well, in wellbore_key order."
                  }
                },
                "additionalProperties": false
              },
              "boe": {
                "type": "object",
                "description": "boe: the asked measures.",
                "required": [],
                "properties": {
                  "cum": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "The (normalised) value at the ip_day, rounded as a curve's mean; null past the well's history."
                      },
                      "description": "One well, parallel to ip_days."
                    },
                    "description": "One per well, in wellbore_key order."
                  },
                  "rate": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "The (normalised) value at the ip_day, rounded as a curve's mean; null past the well's history."
                      },
                      "description": "One well, parallel to ip_days."
                    },
                    "description": "One per well, in wellbore_key order."
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "WellsProductionRequest": {
        "type": "object",
        "description": "Wells whose production to read.",
        "required": [
          "keys"
        ],
        "properties": {
          "keys": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A wellbore key.",
              "minLength": 1,
              "maxLength": 200
            },
            "description": "Wellbore keys, 1 to 50; a repeat counts once.",
            "minItems": 1,
            "maxItems": 50
          },
          "ip_days": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "An ip_day: 1, or a multiple of 30.",
              "minimum": 1
            },
            "description": "Only the rows at these ip_days, at most 240 (a repeat counts once in the answer); absent, every row.",
            "minItems": 1,
            "maxItems": 240
          }
        },
        "additionalProperties": false
      },
      "WellsProduction": {
        "type": "object",
        "description": "Several wells' production.",
        "required": [
          "count",
          "wells"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "Wells.",
            "minimum": 1
          },
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Production"
            },
            "description": "Each well as GET /wells/{key}/production answers it (its rows at ip_days, when sent), in request order."
          }
        },
        "additionalProperties": false
      },
      "InputDistribution": {
        "type": "object",
        "description": "Training distribution for one model input.",
        "required": [
          "unit",
          "rows",
          "blank",
          "fill",
          "ranged",
          "min",
          "max",
          "quantiles",
          "histogram",
          "levels"
        ],
        "properties": {
          "unit": {
            "type": "string",
            "description": "The input's unit (ft, lb/ft, bbl/ft, deg, fraction and so on). An empty string when the input is unitless or its unit isn't documented."
          },
          "rows": {
            "type": "integer",
            "description": "The model's training rows (well x ip_day).",
            "minimum": 0
          },
          "blank": {
            "type": "integer",
            "description": "Rows that are null or NaN.",
            "minimum": 0
          },
          "fill": {
            "type": "integer",
            "description": "Rows holding the features' no-neighbor value. See the input's fill.",
            "minimum": 0
          },
          "ranged": {
            "type": "integer",
            "description": "rows - blank - fill. Only these rows enter min, max, quantiles and histogram.",
            "minimum": 0
          },
          "min": {
            "type": [
              "number",
              "null"
            ],
            "description": "Minimum ranged value. Null for a category or without ranged rows."
          },
          "max": {
            "type": [
              "number",
              "null"
            ],
            "description": "Maximum ranged value. Null for a category or without ranged rows."
          },
          "quantiles": {
            "anyOf": [
              {
                "type": "object",
                "description": "Exact quantiles over ranged rows.",
                "required": [
                  "p01",
                  "p10",
                  "p50",
                  "p90",
                  "p99"
                ],
                "properties": {
                  "p01": {
                    "type": "number",
                    "description": "Exact 1st percentile. Equal to the input's p01."
                  },
                  "p10": {
                    "type": "number",
                    "description": "Exact 10th percentile."
                  },
                  "p50": {
                    "type": "number",
                    "description": "Exact median."
                  },
                  "p90": {
                    "type": "number",
                    "description": "Exact 90th percentile."
                  },
                  "p99": {
                    "type": "number",
                    "description": "Exact 99th percentile. Equal to the input's p99."
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "Null for a category or without ranged values. Compare a planned well input with these quantiles to place it in the training data."
          },
          "histogram": {
            "anyOf": [
              {
                "type": "object",
                "description": "sum(counts) + below + above = ranged.",
                "required": [
                  "edges",
                  "counts",
                  "below",
                  "above"
                ],
                "properties": {
                  "edges": {
                    "type": "array",
                    "items": {
                      "type": "number",
                      "description": "Bin edge."
                    },
                    "description": "21 edges of 20 equal-width bins from p01 to p99. When p01 = p99 there is one bin with edges [p01, p99]."
                  },
                  "counts": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "description": "Rows in the bin.",
                      "minimum": 0
                    },
                    "description": "Bin i holds edges[i] <= x < edges[i+1]. The last bin also holds x = p99."
                  },
                  "below": {
                    "type": "integer",
                    "description": "Ranged rows under p01.",
                    "minimum": 0
                  },
                  "above": {
                    "type": "integer",
                    "description": "Ranged rows over p99.",
                    "minimum": 0
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "Null for a category or without ranged values. Add counts below a planned well input to place it in the training data."
          },
          "levels": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "description": "One category level.",
              "required": [
                "level",
                "rows"
              ],
              "properties": {
                "level": {
                  "type": "string",
                  "description": "Category level."
                },
                "rows": {
                  "type": "integer",
                  "description": "Rows at this level.",
                  "minimum": 0
                }
              },
              "additionalProperties": false
            },
            "description": "Category counts ordered by rows descending, then level. A category has no quantiles or histogram. Null for a numeric input."
          }
        },
        "additionalProperties": false
      },
      "ModelInput": {
        "type": "object",
        "description": "One model input and its training range.",
        "required": [
          "feature",
          "label",
          "kind",
          "p01",
          "p99",
          "blank_share",
          "levels",
          "fill"
        ],
        "properties": {
          "feature": {
            "type": "string",
            "description": "Model feature, as novi_lateral_length."
          },
          "label": {
            "type": "string",
            "description": "Its display name, as Lateral length."
          },
          "kind": {
            "type": "string",
            "description": "numeric or category.",
            "enum": [
              "numeric",
              "category"
            ]
          },
          "p01": {
            "type": [
              "number",
              "null"
            ],
            "description": "1st percentile over training rows, leaving out the no-neighbor value; null for a category."
          },
          "p99": {
            "type": [
              "number",
              "null"
            ],
            "description": "99th percentile over training rows, the same way; null for a category."
          },
          "blank_share": {
            "type": "number",
            "description": "Share of training rows where it is blank.",
            "minimum": 0,
            "maximum": 1
          },
          "levels": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "A category's levels in training, sorted; null for a number."
          },
          "fill": {
            "type": [
              "number",
              "null"
            ],
            "description": "The features' value for no such neighbor (days online -1, distances at the spacing defaults), which p01 and p99 leave out; null when it has none."
          },
          "group": {
            "type": "string",
            "description": "With include=groups: the input's group as Novi's Intel basin report catalog groups model features: geology, spacing, depletion (parents' prior production: novi_spacing_sum_prior_* and novi_spacing_delgados_p*, as the depletion chain reads them), completion, location, or other.",
            "enum": [
              "geology",
              "spacing",
              "depletion",
              "completion",
              "location",
              "other"
            ]
          },
          "distribution": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/InputDistribution"
              },
              {
                "type": "null"
              }
            ],
            "description": "With include=distribution. Null when the card's distribution is unavailable or the model's file has no row for this input."
          }
        },
        "additionalProperties": false
      },
      "ModelSpan": {
        "type": "object",
        "description": "First production range.",
        "required": [
          "from",
          "to"
        ],
        "properties": {
          "from": {
            "type": [
              "string",
              "null"
            ],
            "description": "Earliest first production.",
            "format": "date"
          },
          "to": {
            "type": [
              "string",
              "null"
            ],
            "description": "Latest first production.",
            "format": "date"
          }
        },
        "additionalProperties": false
      },
      "ModelCard": {
        "type": "object",
        "description": "A forecast model's card.",
        "required": [
          "model_num",
          "stream",
          "target",
          "unit",
          "sample_data",
          "served_fit",
          "trained_on",
          "ip_days",
          "versions",
          "training",
          "holdout",
          "inputs",
          "bands",
          "eur",
          "evaluation"
        ],
        "properties": {
          "model_num": {
            "type": "string",
            "description": "Model number, as GET /dataset models[] names it."
          },
          "stream": {
            "type": "string",
            "description": "Stream.",
            "enum": [
              "oil",
              "gas",
              "water"
            ]
          },
          "target": {
            "type": [
              "string",
              "null"
            ],
            "description": "Target column, as novi_oil; null when the dataset doesn't record it."
          },
          "unit": {
            "type": "string",
            "description": "Unit of its predictions.",
            "enum": [
              "bbl",
              "mcf"
            ]
          },
          "sample_data": {
            "type": "boolean",
            "description": "True when the figures come from synthetic sample data."
          },
          "served_fit": {
            "type": "string",
            "description": "The fit that serves forecasts: all, refit on training and holdout wells.",
            "enum": [
              "all"
            ]
          },
          "served_fit_wells": {
            "type": [
              "integer",
              "null"
            ],
            "description": "With include=served_fit_wells: the distinct wells the served `all` fit was trained on, the training and holdout wells of the build's stored predictions with a well in both counted once; null unless the build stores predictions for both splits.",
            "minimum": 0
          },
          "trained_on": {
            "type": "string",
            "description": "What the served fit saw, in words."
          },
          "ip_days": {
            "type": "array",
            "items": {
              "type": "integer",
              "description": "Day."
            },
            "description": "ip_days the model predicts."
          },
          "versions": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "type": "string"
            },
            "description": "Package versions of the fit, by package name; null when the build records none, as on the sample stack."
          },
          "training": {
            "anyOf": [
              {
                "type": "object",
                "description": "The train fit's training wells.",
                "required": [
                  "wells",
                  "rows",
                  "first_production"
                ],
                "properties": {
                  "wells": {
                    "type": "integer",
                    "description": "Training wells.",
                    "minimum": 0
                  },
                  "rows": {
                    "type": "integer",
                    "description": "Training rows (well × ip_day).",
                    "minimum": 0
                  },
                  "first_production": {
                    "$ref": "#/components/schemas/ModelSpan"
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The pre-refit train fit's training wells; null when the build doesn't record them."
          },
          "holdout": {
            "anyOf": [
              {
                "type": "object",
                "description": "Wells the train fit never saw.",
                "required": [
                  "wells",
                  "rule",
                  "first_production"
                ],
                "properties": {
                  "wells": {
                    "type": "integer",
                    "description": "Holdout wells.",
                    "minimum": 0
                  },
                  "rule": {
                    "type": "string",
                    "description": "How they were chosen, in words."
                  },
                  "first_production": {
                    "$ref": "#/components/schemas/ModelSpan"
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The train fit's holdout wells; null when the build has no stored predictions."
          },
          "inputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ModelInput"
            },
            "description": "Each input in feature order with its training range; empty without training statistics."
          },
          "bands": {
            "type": "object",
            "description": "P10/P90 bands, as GET /dataset bands reports them for this stream.",
            "required": [
              "available",
              "method",
              "reason"
            ],
            "properties": {
              "available": {
                "type": "boolean",
                "description": "Whether the model has a stored P10/P90 bands fit."
              },
              "method": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "How the bands are made."
              },
              "reason": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Why not, when it hasn't."
              }
            },
            "additionalProperties": false
          },
          "eur": {
            "type": "object",
            "description": "EUR.",
            "required": [
              "available"
            ],
            "properties": {
              "available": {
                "type": "boolean",
                "description": "Whether `eur: true` extends this stream's forecasts to EUR (oil and gas, when the server fits EUR). False for water, which takes `eur_water: true`."
              }
            },
            "additionalProperties": false
          },
          "evaluation": {
            "type": "object",
            "description": "Held-out accuracy.",
            "required": [
              "available",
              "reason",
              "href"
            ],
            "properties": {
              "available": {
                "type": "boolean",
                "description": "Whether GET /models/{model_num}/evaluation has figures for this model."
              },
              "reason": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Why not, when it hasn't."
              },
              "href": {
                "type": "string",
                "description": "Its evaluation's path."
              }
            },
            "additionalProperties": false
          },
          "distribution": {
            "type": "object",
            "description": "With include=distribution.",
            "required": [
              "available",
              "reason"
            ],
            "properties": {
              "available": {
                "type": "boolean",
                "description": "Whether the training distribution was read."
              },
              "reason": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Why not, when it isn't available."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "ModelList": {
        "type": "object",
        "description": "The forecast models.",
        "required": [
          "models"
        ],
        "properties": {
          "models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ModelCard"
            },
            "description": "One per stream: oil, gas and water."
          }
        },
        "additionalProperties": false
      },
      "ModelEvaluationRow": {
        "type": "object",
        "description": "One ip_day's accuracy; every metric null with fewer than min_wells wells.",
        "required": [
          "ip_day",
          "wells",
          "mdape",
          "median_ratio",
          "within_10",
          "within_25",
          "bias",
          "correlation"
        ],
        "properties": {
          "ip_day": {
            "type": "integer",
            "description": "Days since first production."
          },
          "wells": {
            "type": "integer",
            "description": "Wells that had reached it with an actual above 0 and a stored prediction: the wells every metric is over (a blank prediction is left out).",
            "minimum": 0
          },
          "mdape": {
            "type": [
              "number",
              "null"
            ],
            "description": "Median of |predicted − actual| / actual, over wells with actual > 0."
          },
          "median_ratio": {
            "type": [
              "number",
              "null"
            ],
            "description": "Median of predicted / actual."
          },
          "within_10": {
            "type": [
              "number",
              "null"
            ],
            "description": "Share of wells with |predicted / actual − 1| at most 0.10."
          },
          "within_25": {
            "type": [
              "number",
              "null"
            ],
            "description": "Share of wells with |predicted / actual − 1| at most 0.25."
          },
          "bias": {
            "type": [
              "number",
              "null"
            ],
            "description": "Median of predicted / actual − 1: above 0 over-predicts."
          },
          "correlation": {
            "type": [
              "number",
              "null"
            ],
            "description": "Pearson's r of predicted and actual."
          }
        },
        "additionalProperties": false
      },
      "ModelEvaluationScope": {
        "description": "With near or bbox: the area every row and include=wells are over, matched by lateral midpoint as GET /wells matches wells; `wells` counts the split's wells there with a stored prediction at any ip_day, whatever ip_day is sent.",
        "oneOf": [
          {
            "type": "object",
            "description": "A radius around a point.",
            "required": [
              "near",
              "radius_mi",
              "wells"
            ],
            "properties": {
              "near": {
                "type": "array",
                "items": {
                  "type": "number",
                  "description": "Degrees."
                },
                "description": "Center [lng, lat].",
                "minItems": 2,
                "maxItems": 2
              },
              "radius_mi": {
                "type": "number",
                "description": "The radius applied, in miles: radius_mi, or 5 when it wasn't sent.",
                "exclusiveMinimum": 0,
                "maximum": 100
              },
              "wells": {
                "type": "integer",
                "description": "Distinct wells with a stored prediction in the area at any ip_day.",
                "minimum": 0
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "A bounding box.",
            "required": [
              "bbox",
              "wells"
            ],
            "properties": {
              "bbox": {
                "type": "array",
                "items": {
                  "type": "number",
                  "description": "Degrees."
                },
                "description": "[west, south, east, north].",
                "minItems": 4,
                "maxItems": 4
              },
              "wells": {
                "type": "integer",
                "description": "Distinct wells with a stored prediction in the area at any ip_day.",
                "minimum": 0
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "ModelEvaluation": {
        "type": "object",
        "description": "A model's accuracy.",
        "required": [
          "model_num",
          "sample_data",
          "fit",
          "split",
          "rule",
          "as_of",
          "min_wells",
          "group_by",
          "groups"
        ],
        "properties": {
          "model_num": {
            "type": "string",
            "description": "Model number."
          },
          "sample_data": {
            "type": "boolean",
            "description": "True when the figures come from synthetic sample data."
          },
          "fit": {
            "type": "string",
            "description": "The fit measured: the pre-refit train fit.",
            "enum": [
              "train"
            ]
          },
          "split": {
            "type": "string",
            "description": "The wells measured.",
            "enum": [
              "holdout",
              "train"
            ]
          },
          "rule": {
            "type": "string",
            "description": "How holdout wells were chosen, in words."
          },
          "as_of": {
            "type": [
              "string",
              "null"
            ],
            "description": "The production date actuals run to.",
            "format": "date"
          },
          "min_wells": {
            "type": "integer",
            "description": "Fewest wells for a cell's metrics.",
            "minimum": 1
          },
          "group_by": {
            "type": "string",
            "description": "How groups split the wells.",
            "enum": [
              "none",
              "formation",
              "first_year"
            ]
          },
          "scope": {
            "$ref": "#/components/schemas/ModelEvaluationScope",
            "description": "With near or bbox: the applied area and its count of split wells with a stored prediction at any ip_day."
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One group.",
              "required": [
                "group",
                "rows"
              ],
              "properties": {
                "group": {
                  "type": [
                    "string",
                    "integer",
                    "null"
                  ],
                  "description": "The formation or first-production year; null with group_by=none, and for wells without one (listed last)."
                },
                "rows": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ModelEvaluationRow"
                  },
                  "description": "By ip_day, ascending."
                }
              },
              "additionalProperties": false
            },
            "description": "One group, or one per formation or year; none (`[]`) when near or bbox holds none of the split's wells (`scope.wells` 0)."
          },
          "wells": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ModelEvaluationWell"
            },
            "description": "With include=wells: each well behind the ip_day's metrics, by formation then key."
          }
        },
        "additionalProperties": false
      },
      "ModelEvaluationWell": {
        "type": "object",
        "description": "One well in an evaluation cell.",
        "required": [
          "wellbore_key",
          "formation",
          "first_year",
          "predicted",
          "actual",
          "ape"
        ],
        "properties": {
          "wellbore_key": {
            "type": "string",
            "description": "Wellbore key."
          },
          "formation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Formation."
          },
          "first_year": {
            "type": [
              "integer",
              "null"
            ],
            "description": "First-production year."
          },
          "predicted": {
            "type": "number",
            "description": "The train fit's stored prediction of the cumulative at the ip_day, in the stream's unit, to 0.1."
          },
          "actual": {
            "type": "number",
            "description": "The well's actual cumulative there, above 0, to 0.1."
          },
          "ape": {
            "type": "number",
            "description": "|predicted − actual| / actual, before rounding, to 4 decimals.",
            "minimum": 0
          },
          "group": {
            "type": [
              "string",
              "integer",
              "null"
            ],
            "description": "With group_by: the well's group, as in `groups` (its formation or first-production year)."
          }
        },
        "additionalProperties": false
      },
      "ModelBaselines": {
        "type": "object",
        "description": "A model's SHAP baselines.",
        "required": [
          "model_num",
          "sample_data",
          "unit",
          "source",
          "min_wells",
          "baselines"
        ],
        "properties": {
          "model_num": {
            "type": "string",
            "description": "Model number."
          },
          "sample_data": {
            "type": "boolean",
            "description": "True when the figures come from synthetic sample data."
          },
          "unit": {
            "type": "string",
            "description": "Unit of every value.",
            "enum": [
              "bbl",
              "mcf"
            ]
          },
          "source": {
            "type": "string",
            "description": "The population the means are over, in words."
          },
          "min_wells": {
            "type": "integer",
            "description": "Fewest wells for a value.",
            "minimum": 1
          },
          "baselines": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One reference.",
              "required": [
                "reference",
                "formation",
                "label",
                "rows"
              ],
              "properties": {
                "reference": {
                  "type": "string",
                  "description": "The reference.",
                  "enum": [
                    "formation",
                    "dataset"
                  ]
                },
                "formation": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The formation; null for dataset."
                },
                "label": {
                  "type": "string",
                  "description": "The reference in words, as Typical Wolfcamp A well."
                },
                "rows": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "description": "One ip_day.",
                    "required": [
                      "ip_day",
                      "wells",
                      "expected_value",
                      "value",
                      "values"
                    ],
                    "properties": {
                      "ip_day": {
                        "type": "integer",
                        "description": "Days since first production."
                      },
                      "wells": {
                        "type": "integer",
                        "description": "Reference wells at this ip_day.",
                        "minimum": 0
                      },
                      "expected_value": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "The reference wells' mean expected value at this ip_day."
                      },
                      "value": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "The reference's mean SHAP total: expected_value plus values, its mean forecast only where the model's SHAP is additive; null with fewer than min_wells wells."
                      },
                      "values": {
                        "type": "object",
                        "description": "Each feature's mean SHAP contribution over the reference's wells (a blank one counts as 0); empty with fewer than min_wells wells.",
                        "additionalProperties": {
                          "type": [
                            "number",
                            "null"
                          ]
                        }
                      }
                    },
                    "additionalProperties": false
                  },
                  "description": "By ip_day, ascending."
                }
              },
              "additionalProperties": false
            },
            "description": "Each formation in GET /formations order, then dataset."
          }
        },
        "additionalProperties": false
      },
      "WellStreamPredictions": {
        "description": "One stream's stored predictions for the well, or why there are none.",
        "oneOf": [
          {
            "type": "object",
            "description": "Predictions.",
            "required": [
              "model_num",
              "fit",
              "split",
              "in_sample",
              "unit",
              "ip_days",
              "predicted",
              "actual",
              "ape"
            ],
            "properties": {
              "model_num": {
                "type": "string",
                "description": "Model number."
              },
              "fit": {
                "type": "string",
                "description": "The fit predicted with.",
                "enum": [
                  "train"
                ]
              },
              "split": {
                "type": "string",
                "description": "holdout: the train fit never saw the well; train: it trained on it.",
                "enum": [
                  "holdout",
                  "train"
                ]
              },
              "in_sample": {
                "type": "boolean",
                "description": "True for a training well: its error reads better than held-out."
              },
              "unit": {
                "type": "string",
                "description": "Volume unit.",
                "enum": [
                  "bbl",
                  "mcf"
                ]
              },
              "ip_days": {
                "type": "array",
                "items": {
                  "type": "integer",
                  "description": "Days since first production."
                },
                "description": "ip_days, ascending."
              },
              "predicted": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Predicted cumulative."
                },
                "description": "One per ip_day."
              },
              "actual": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Actual cumulative; null past the well's history."
                },
                "description": "One per ip_day."
              },
              "ape": {
                "type": "array",
                "items": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "|predicted − actual| / actual; null without an actual above 0."
                },
                "description": "One per ip_day."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "object",
            "description": "No predictions.",
            "required": [
              "model_num",
              "fit",
              "split",
              "reason"
            ],
            "properties": {
              "model_num": {
                "type": "string",
                "description": "Model number."
              },
              "fit": {
                "type": "string",
                "description": "The fit.",
                "enum": [
                  "train"
                ]
              },
              "split": {
                "type": "null",
                "description": "None."
              },
              "reason": {
                "type": "string",
                "description": "Why there are none."
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "WellPredictions": {
        "type": "object",
        "description": "An existing well's stored predictions beside its actuals.",
        "required": [
          "wellbore_key",
          "sample_data",
          "streams"
        ],
        "properties": {
          "wellbore_key": {
            "type": "string",
            "description": "Wellbore key."
          },
          "sample_data": {
            "type": "boolean",
            "description": "True when the figures come from synthetic sample data."
          },
          "streams": {
            "type": "object",
            "description": "Per stream. Only the streams the model set serves (GET /model-sets `streams`): a set serving gas alone answers gas alone.",
            "required": [],
            "properties": {
              "oil": {
                "$ref": "#/components/schemas/WellStreamPredictions"
              },
              "gas": {
                "$ref": "#/components/schemas/WellStreamPredictions"
              },
              "water": {
                "$ref": "#/components/schemas/WellStreamPredictions"
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "PlanDrivers": {
        "type": "object",
        "description": "A plan's drivers for one design, stream and ip_day.",
        "required": [
          "id",
          "design",
          "stream",
          "ip_day",
          "unit",
          "placed",
          "explained",
          "drivers",
          "wells"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Plan id.",
            "format": "uuid"
          },
          "design": {
            "type": "integer",
            "description": "The design's position in the plan's `designs`, from 0.",
            "minimum": 0
          },
          "stream": {
            "type": "string",
            "description": "The stream whose model is explained.",
            "enum": [
              "oil",
              "gas"
            ]
          },
          "scenario": {
            "type": "string",
            "description": "The scenario explained, when `scenario` was sent."
          },
          "ip_day": {
            "type": "integer",
            "description": "The ip_day explained."
          },
          "unit": {
            "type": "string",
            "description": "bbl for oil, mcf for gas, as the explanation's.",
            "enum": [
              "bbl",
              "mcf"
            ]
          },
          "placed": {
            "type": "integer",
            "description": "The plan's placed wells; `wells` lists the first 100.",
            "minimum": 0
          },
          "explained": {
            "type": "integer",
            "description": "Wells listed with SHAP; the means are over these.",
            "minimum": 0
          },
          "expected_value": {
            "type": [
              "number",
              "null"
            ],
            "description": "With include=path: the explained wells' mean expected value in `unit`, where the path starts; null when no well is explained or one has none."
          },
          "mean_forecast": {
            "type": [
              "number",
              "null"
            ],
            "description": "With include=path: the explained wells' mean served forecast at `ip_day` in `unit`, where the path ends; null when no well is explained or one has no forecast served there."
          },
          "mean_residual": {
            "type": [
              "number",
              "null"
            ],
            "description": "With include=path: `mean_forecast` − `expected_value` − the sum of `mean_shap`, unrounded: the part of the mean forecast the SHAP values don't attribute. Null when `mean_forecast` or `expected_value` is null."
          },
          "drivers": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One input's mean contribution.",
              "required": [
                "feature",
                "mean_abs_shap",
                "wells"
              ],
              "properties": {
                "feature": {
                  "type": "string",
                  "description": "The model input as explanation SHAP rows name it."
                },
                "mean_abs_shap": {
                  "type": "number",
                  "description": "Mean |SHAP| over the explained wells in `unit`, an input a row leaves out counting as 0."
                },
                "mean_shap": {
                  "type": "number",
                  "description": "With include=path: mean SHAP over the explained wells in `unit`, signed, an input a row leaves out counting as 0."
                },
                "wells": {
                  "type": "integer",
                  "description": "The explained wells whose row has the input.",
                  "minimum": 0
                }
              },
              "additionalProperties": false
            },
            "description": "Sorted by mean_abs_shap, largest first, ties by feature."
          },
          "wells": {
            "type": "array",
            "items": {
              "description": "A placed well with SHAP, or why it has no forecast to explain.",
              "oneOf": [
                {
                  "$ref": "#/components/schemas/PlanDriverWell"
                },
                {
                  "$ref": "#/components/schemas/PlanDriverWellError"
                }
              ]
            },
            "description": "Placed wells in plan order.",
            "maxItems": 100
          }
        },
        "additionalProperties": false
      },
      "PlanDriverWell": {
        "type": "object",
        "description": "An explained well.",
        "required": [
          "index",
          "label",
          "expected_value",
          "values"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "The well's position in the plan, from 0.",
            "minimum": 0
          },
          "label": {
            "type": "string",
            "description": "The well's label."
          },
          "name": {
            "type": "string",
            "description": "The name the request gave the well, trimmed; only when it gave one. `label` doesn't change."
          },
          "expected_value": {
            "type": [
              "number",
              "null"
            ],
            "description": "The model's expected value, as the explanation's SHAP row."
          },
          "values": {
            "type": "object",
            "additionalProperties": {
              "type": [
                "number",
                "null"
              ],
              "description": "The input's SHAP value."
            },
            "description": "Values by feature, as an explanation SHAP row's `values`."
          }
        },
        "additionalProperties": false
      },
      "PlanDriverWellError": {
        "type": "object",
        "description": "A well without a forecast to explain.",
        "required": [
          "index",
          "label",
          "error"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "The well's position in the plan, from 0.",
            "minimum": 0
          },
          "label": {
            "type": "string",
            "description": "The well's label."
          },
          "name": {
            "type": "string",
            "description": "The name the request gave the well, trimmed; only when it gave one. `label` doesn't change."
          },
          "error": {
            "type": "string",
            "description": "Why the well has no forecast to explain."
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A Novi API token, created in the Forecasts app under Settings > API tokens."
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
