Skip to content
Developers
Get an API token

Save a document

Saves a filter set, completion design, type curve, view or settings object.

Save a document

POST/saved/{collection}

Saves a filter set, completion design, type curve, view or settings object.

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

Retries

The same Idempotency-Key and body answer the first document; keys are scoped to the tenant, the signed-in creator and the collection.

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

Path parameters

  • collectionstringRequired

    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.

    "filter-sets""completion-designs""type-curves""views""settings""assumption-sets""column-mappings""plan-views"

Header parameters

  • Idempotency-KeystringOptional

    pattern ^[A-Za-z0-9._:-]{1,128}$

    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.

    The 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).

    • Keys are per operation, and only a success records one: retry a 502, 503, 504 or a lost response with the same key.
    • 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.
      • 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.
      • 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.
    • 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.
    • 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.
    • A replay of a plan or export the server has dropped is a 404.

Request bodyRequired

application/json

Document content and optional plan attachment.

  • namestringRequired

    1 to 100 characters

    Document name.

  • bodyobjectRequired

    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.

    • completion-designs: one design as designs[] takes it (DesignInput), its formations unchecked against a dataset; any other body is a 400.
    • 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.
      • A set on a model set the caller can't use isn't listed and answers 404.
    • column-mappings: { column_hints, formations? }, checked on each save: any other key or a bad value is a 400 naming it (body.<field>).
      • column_hints (required): as POST /inventories/read takes them.
      • 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.
    • 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.
  • visibilitystringOptional

    Default "tenant"

    Audience: private answers only its creator, tenant every user of the tenant.

    "private""tenant"
  • plan_idstring or nullOptional

    Format uuid

    Attached plan UUID; omitted or null detaches.

Responses

201 Created

Saved document and ETag.

  • idstringRequired

    Format uuid

    Document id.

  • collectionstringRequired

    Collection.

    "filter-sets""completion-designs""type-curves""views""settings""assumption-sets""column-mappings""plan-views"
  • namestringRequired

    Name.

  • visibilitystringRequired

    Recorded audience.

    "private""tenant"
  • plan_idstring or nullRequired

    Format uuid

    Attached plan UUID.

  • created_atstringRequired

    Format date-time

    Creation time.

  • updated_atstringRequired

    Format date-time

    Last update.

  • created_bystring or nullRequired

    The creator's email; null for older documents. A private document with none answers the whole tenant.

  • etagstringRequired

    Current ETag including quotes; send as If-Match when replacing.

  • bodyobjectRequired

    Saved JSON content.

  • versionintegerOptional

    ≥ 1

    assumption-sets only: 1 when created, one more on each PUT. POST /plans assumption_set.version names it.

  • model_setstringOptional

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

    assumption-sets only: the body's model_set, the model set the set was made on.

Errors

StatusWhen
404

No such well, grid, plan or route.

409

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.

413

The request body is over 64 MB.

503

With Redis, the Redis that keeps Idempotency-Key records isn't answering; retry with the same key.

Shared errors400401403500What they mean