Share a completed plan
Creates a read link to a done plan and saves the plan.
Share a completed plan
/plans/{id}/sharesCreates 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.
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.
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.
Parameters
Path parameters
idstringRequiredFormat
uuidPlan id from POST /plans.
Query parameters
model_setstringOptionalpattern ^[a-z0-9][a-z0-9-]{0,62}$
The model set to answer from, an
idfrom GET /model-sets. Absent: the set GET /model-sets names asdefault, the base dataset unless the server answers from a published set.model_set=defaultreaches 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 oncedefaultis 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'splan.id, or a comparison'sa.planandb.plan, also undersource.comparison) reaches it withoutmodel_set. - An explicit
model_setwins; naming resources of two sets in one request is a 400.
Request body
application/json
Link audience and optional lifetime.
visibilitystringRequiredIntended audience, recorded with the share; it doesn't change who can read it.
"link""tenant"expires_in_daysintegerOptional≥ 1, ≤ 365
Lifetime, otherwise no expiry.
Responses
201 Created
The token, returned only here.
idstringRequiredFormat
uuidShare id.
tokenstringRequiredpattern ^[A-Za-z0-9_-]{22}$
Secret token, returned only here.
visibilitystringRequiredIntended audience.
"link""tenant"created_atstringRequiredFormat
date-timeCreation time.
expires_atstring or nullRequiredFormat
date-timeExpiry, null for no expiry.
revoked_atanyRequiredNew shares are unrevoked.
planobjectRequiredShared plan.
ShowHide 3 child fields
idstringRequiredFormat
uuidPlan id.
namestring or nullRequiredPlan name.
model_setstringRequiredPlan model set.
linksobjectRequiredShare URL.
ShowHide 1 child field
selfstringRequiredResolve this token on this API.
Errors
| Status | When |
|---|---|
| 404 | No such well, grid, plan or route. |
| 409 | The request conflicts with the state of the plan or resource it names, and |
| 413 | The request body is over 10 MB. |
Shared errors400401403500503What they mean