Skip to content
Developers
Get an API token

Share a completed plan

Creates a read link to a done plan and saves the plan.

Share a completed plan

POST/plans/{id}/shares

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.

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

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

application/json

Link audience and optional lifetime.

  • visibilitystringRequired

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

  • idstringRequired

    Format uuid

    Share id.

  • tokenstringRequired

    pattern ^[A-Za-z0-9_-]{22}$

    Secret token, returned only here.

  • visibilitystringRequired

    Intended audience.

    "link""tenant"
  • created_atstringRequired

    Format date-time

    Creation time.

  • expires_atstring or nullRequired

    Format date-time

    Expiry, null for no expiry.

  • revoked_atanyRequired

    New shares are unrevoked.

  • planobjectRequired

    Shared plan.

    ShowHide 3 child fields
    • idstringRequired

      Format uuid

      Plan id.

    • namestring or nullRequired

      Plan name.

    • model_setstringRequired

      Plan model set.

  • linksobjectRequired

    Share URL.

    ShowHide 1 child field
    • selfstringRequired

      Resolve this token on this API.

Errors

StatusWhen
404

No such well, grid, plan or route.

409

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.

413

The request body is over 10 MB.

Shared errors400401403500503What they mean