Skip to content
Developers
Get an API token

Read completion designs from a file

Completion designs from a CSV or an Excel workbook as named designs, ready for a plan's designs, with what became of each row.

Read completion designs from a file

POST/completion-designs/read

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.

Send a Novi API token as a bearer token on every request. Authentication
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 ….

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):

  • name: designname, design, completiondesign, name
  • formation: noviformation, targetformation, formation, targetzone, landingzone, zone
  • fluid_bbl_per_ft: novicalcfluidperlength, fluidbblperft, fluidperft, fluidperlength, fluid, fluidbblft
  • fluid_gal_per_ft: fluidgalperft, galperft, fluidgalft
  • proppant_lb_per_ft: novicalcproppantperlength, proppantlbperft, proppantperft, proppantperlength, propperft, proppant, sand, sandlbperft, proppantlbft, sandlbft
  • fluid_bbl_per_stage: fluidbblperstage, fluidperstage, fluidbblstage
  • proppant_lb_per_stage: proppantlbperstage, proppantperstage, sandperstage, proppantlbstage, sandlbstage
  • stage_length_ft: novistagelength, novicalcstagespacing, stagelengthft, stagelength, stagespacing, stagespacingft, stagelen
  • clusters_per_stage: noviclustersperstage, novicalcclustersperstage, clustersperstage, cluststg
  • frac_rate_bbl_per_min: novifracrate, fracratebblpermin, fracrate, fracratebblmin, fracratebpm, fracbpm

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

Rows

A CSV row with more cells than the header is left out.

  • Rows with the same name are one design; a blank name, or one over 60 characters, leaves the row out.
  • 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.
  • A repeat of a name and formation, or of a name's own row, is left out, naming the row it repeats.
Values

Numbers are written as 2700 or 2.7e3, without thousands separators.

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

Errors

400 with details.field naming file, csv, sheet, or include and include[0] (an unknown value, with details.allowed).

Parameters

Query parameters

  • model_setstringOptional

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

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

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

Request bodyRequired

The file as a multipart upload, or CSV text in JSON.

  • filestringRequired

    File

    A CSV or .xlsx workbook.

  • sheetstringOptional

    Workbook sheet name in any case or index from 0; absent, the first. With CSV, a 400.

  • includestringOptional

    JSON text, as ["sheets"]: a workbook's answer adds sheet and sheets; any other file's answer is unchanged.

Responses

200 OK

Named designs and every row in file order.

  • countintegerRequired

    ≥ 0

    Number of designs.

  • formatstringRequired

    How the file was read.

    "csv""xlsx"
  • columnsobjectRequired

    Each role and its header as read; null when absent.

    ShowHide 10 child fields
    • namestring or nullRequired

      Design name header or null.

    • formationstring or nullRequired

      Formation header or null.

    • fluid_bbl_per_ftstring or nullRequired

      Fluid bbl/ft header or null.

    • fluid_gal_per_ftstring or nullRequired

      Fluid gal/ft header or null.

    • proppant_lb_per_ftstring or nullRequired

      Proppant lb/ft header or null.

    • fluid_bbl_per_stagestring or nullRequired

      Fluid per-stage header or null.

    • proppant_lb_per_stagestring or nullRequired

      Proppant per-stage header or null.

    • stage_length_ftstring or nullRequired

      Stage length header or null.

    • clusters_per_stagestringOptional

      Clusters per stage header; only when the file has the column.

    • frac_rate_bbl_per_minstringOptional

      Frac rate header; only when the file has the column.

  • fieldsarray of stringsRequired

    Headers in file order.

  • designsarray of objectsRequired

    Named designs in first-appearance order, ready to post as designs; formations is always an array.

    ShowHide 7 child fields in each item
    • namestring or nullOptional

      up to 60 characters

      Your name for the design; defaults to Design 1, Design 2, ….

    • fluid_bbl_per_ftnumber or nullOptional

      > 0, < 1000

      Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

    • proppant_lb_per_ftnumber or nullOptional

      > 0, < 20000

      Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

    • stage_length_ftnumber or nullOptional

      > 0, < 2000

      Stage length in ft.

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

    • clusters_per_stagenumber or nullOptional

      > 0, < 100

      Perforation clusters per stage; fractions are accepted.

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

    • frac_rate_bbl_per_minnumber or nullOptional

      > 0, < 500

      Frac pump rate in bbl per minute.

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

    • formationsarray of objectsOptional

      Per-formation overrides, each formation at most once.

      ShowHide 6 child fields in each item
      • formationstringRequired

        Formation (case-insensitive).

      • fluid_bbl_per_ftnumber or nullOptional

        > 0, < 1000

        Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

      • proppant_lb_per_ftnumber or nullOptional

        > 0, < 20000

        Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

      • stage_length_ftnumber or nullOptional

        > 0, < 2000

        Stage length in ft.

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

      • clusters_per_stagenumber or nullOptional

        > 0, < 100

        Perforation clusters per stage; fractions are accepted.

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

      • frac_rate_bbl_per_minnumber or nullOptional

        > 0, < 500

        Frac pump rate in bbl per minute.

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

  • rowsarray of objectsRequired

    Every data row in file order; blank lines are left out.

    ShowHide 5 child fields in each item
    • idintegerRequired

      ≥ 0

      Data row from 0, in file order.

    • namestring or nullRequired

      Trimmed name, generated Design N without a name column, or null when blank.

    • formationstring or nullRequired

      Dataset spelling when matched, else the text as written, or null when blank.

    • designinteger or nullRequired

      ≥ 0

      Index in designs, or null when left out.

    • issuesarray of stringsRequired

      Why the row was left out or a value dropped.

  • unknown_formationsarray of objectsRequired

    Most rows first, ties in first-seen order.

    ShowHide 2 child fields in each item
    • valuestringRequired

      First spelling read.

    • rowsintegerRequired

      ≥ 1

      Rows left out.

  • warningsarray of stringsRequired

    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.

  • sheetstringOptional

    The sheet read; only with include ["sheets"], for a workbook.

  • sheetsarray of stringsOptional

    Every sheet in workbook order, chartsheets included, so a position is the index sheet takes; only with include ["sheets"], for a workbook.

Errors

StatusWhen
413

The request body is over 10 MB.

Shared errors400401403500503What they mean