Save a document
Saves a filter set, completion design, type curve, view or settings object.
Save a document
/saved/{collection}Saves a filter set, completion design, type curve, view or settings object.
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
collectionstringRequiredSaved 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-KeystringOptionalpattern ^[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.fieldIdempotency-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: trueand POST /plans/{id}/economics keep each key with its job, as their descriptions say. A POST /plans withdry_run: trueneither keeps nor replays its key. - A replay of a plan or export the server has dropped is a 404.
Request body
application/json
Document content and optional plan attachment.
namestringRequired1 to 100 characters
Document name.
bodyobjectRequiredJSON 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 asdesigns[]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.
visibilitystringOptionalDefault
"tenant"Audience: private answers only its creator, tenant every user of the tenant.
"private""tenant"plan_idstring or nullOptionalFormat
uuidAttached plan UUID; omitted or null detaches.
Responses
201 Created
Saved document and ETag.
idstringRequiredFormat
uuidDocument id.
collectionstringRequiredCollection.
"filter-sets""completion-designs""type-curves""views""settings""assumption-sets""column-mappings""plan-views"namestringRequiredName.
visibilitystringRequiredRecorded audience.
"private""tenant"plan_idstring or nullRequiredFormat
uuidAttached plan UUID.
created_atstringRequiredFormat
date-timeCreation time.
updated_atstringRequiredFormat
date-timeLast update.
created_bystring or nullRequiredThe creator's email; null for older documents. A private document with none answers the whole tenant.
etagstringRequiredCurrent ETag including quotes; send as If-Match when replacing.
bodyobjectRequiredSaved JSON content.
versionintegerOptional≥ 1
assumption-sets only: 1 when created, one more on each PUT. POST /plans assumption_set.version names it.
model_setstringOptionalpattern ^[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
| Status | When |
|---|---|
| 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