Preview using a template

POST/api/templates/{id}/use/preview

Shows what using a template would make, with the connections chosen so far. Makes nothing.

Needs an API token with the Read permission for workflows (workflow:read).

Parameters

Path

idRequired · UUID: The template’s ID.

Body

Optional: what the person has chosen so far.

connectionsOptional · object: A connection of this workspace for each slot: {"c1": "…"}.
valuesOptional · object: Fill-ins, by step name and field, as for Make a workflow from a template.

Read it

slots: each slot, this workspace’s connections for its service (ones needing a new sign-in last) and selected, the one that would fill it.

diagnostics: what Check a definition would report on the workflow as made. canPublish and publishBlockedBy: whether it could go live, and the first reason not. fill: the values the person would be asked for, in step order.

Responses

200OK
The preview.
400VALIDATION_ERROR
The body isn’t JSON, or connections names a slot the template lacks or a connection outside the workspace.
403FORBIDDEN
The token lacks the Read permission for workflows.
404NOT_FOUND
No template with this ID that this workspace may use. An ID that isn’t a UUID answers this too.
422PIECE_NOT_ALLOWED
A step uses an app this workspace may not use.
422CONNECTION_MISMATCH
A connection named for a slot is for another service (details.slot).
422VALIDATION_ERROR
The template uses an app this installation can’t run.
500INTERNAL_ERROR
The template or the workspace’s connections couldn’t be read.
503PIECES_UNAVAILABLE
GoRunner couldn’t check which apps this workspace may use.

Any call can also answer: 401 UNAUTHORIZED · 401 TOKEN_ENDED · 403 TOKEN_SURFACE_OFF · 403 FEATURE_OFF · 403 EMBED_NOT_ALLOWED · 403 EMBED_NOT_AVAILABLE · 403 ACCOUNT_SUSPENDED · 413 PAYLOAD_TOO_LARGE · 415 INVALID_CONTENT_TYPE · 429 RATE_LIMITED · 503 BUSY · 503 PAUSED · 503 SERVICE_UNAVAILABLE. See Errors.

Request

GORUNNER="https://api.gorunner.io"
GORUNNER_TOKEN="grt_…"  # needs Read for workflows
TEMPLATE_ID="your-template-id"

URL="$GORUNNER/api/templates/$TEMPLATE_ID/use/"
URL="${URL}preview"
curl -X POST "$URL" \
  -H "Authorization: Bearer $GORUNNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connections": {
      "c1": "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b"
    }
  }'

const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const TEMPLATE_ID = process.env.TEMPLATE_ID;

const res = await fetch(
  `${GORUNNER}/api/templates/${TEMPLATE_ID}/` +
    `use/preview`,
  {
    method: "POST",
    headers: {
        Authorization: `Bearer ${TOKEN}`,
        "Content-Type": "application/json",
      },
    body: JSON.stringify({
        connections: {
          c1: "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b",
        },
      }),
  },
);
const { data } = await res.json();

import os, requests

GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
TEMPLATE_ID = os.environ["TEMPLATE_ID"]

res = requests.post(
    f"{GORUNNER}/api/templates/{TEMPLATE_ID}/use/"
    f"preview",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
      "connections": {
        "c1": "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b",
      },
    },
)
data = res.json()["data"]

Response · 200 OK, shortened

json

{
  "data": {
    "slots": [
      {
        "key": "c1",
        "pieceId": "postgres",
        "candidates": [
          {
            "id": "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b",
            "name": "Warehouse database",
            "status": "active"
          }
        ],
        "selected": "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b"
      }
    ],
    "diagnostics": [],
    "canPublish": true,
    "publishBlockedBy": null,
    "fill": [],
    "savedHere": true,
    "savedIn": "Orders"
  }
}

Every field

Body

connectionsOptional · object: Slot key → a connection of this workspace made for the slot’s service.
{key}UUID: Each key’s value.
valuesOptional · object: The person’s fill-ins: step name → input key → value, written over the template’s values. A blank value ("", null, []) leaves the field blank. A step or input the template does not have is refused 400 (details.field: values, details.step, details.input).
{key}object: Each key’s value.

Response · 200 OK

dataobject
slotsarray of objects
keystring: The slot (c1, c2, … in the order the steps first use it).
pieceIdstring: The service a connection for it must be for.
pieceNamestring
stepsarray of objects
namestring: trigger for the trigger.
displayNamestring
candidatesarray of objects: This workspace’s connections for the service; those needing a new sign-in (expired, error) last.
idUUID
namestring
statusstring
managedBystring or null: One of partner, null.
selectedUUID or null: The connection that fills it now: the one chosen, else the one the template’s steps named where it is a candidate and works (never one that is error, expired or pending).
diagnosticsarray of objects: What POST /api/workflows/validate would report on the workflow as it would be made, with this workspace’s apps applied. Each with stepLabel (the step as the canvas names it) and fieldLabel (the app’s title for the field; empty when it is not about an app’s field).
severitystring: One of error, warning, info.
codestring: Stable machine-readable identifier for the kind of problem. Switch on this, not on message. The Code step’s own: code_expression_in_code (Code 2.0.0 code holds a {{ steps…/trigger…/$… }}, which 2.0.0 does not replace — in live code it blocks publish, never a save; inside string or template text it is a warning, since 2.0.0 keeps that text as written), code_empty (2.0.0 blank code, blocks publish; 1.0.0 empty code, a warning: it fails at run time), code_v1_expression (Code 1.0.0 pastes {{ }} into the program: a warning when it reads the trigger, else info), code_unavailable_api (require(, import, fetch(, XMLHttpRequest, process.env), code_global_not_here (a 1.0.0 $ name in 2.0.0 code), code_timeout_capped (1.0.0 stops at 30 s whatever Timeout says), code_output_path (steps.<code step>.<key> where the output is {result, logs}), code_returns_result (return { result: … }), code_syntax_error (the code does not compile as its run compiles it, so every run that reaches the step fails before a line of it runs: the message names the line of the code as written; it blocks publish, never a save, and is a warning on a step no run reaches (skipped, or in error steps its step does not route to); a 1.0.0 step whose {{ }} are pasted in before it runs is not checked). A step on Code 1.0.0 only ever gets warnings and info, except for code that cannot compile (code_syntax_error) or is over 256 KB (code_too_large). step_name_too_long (a step’s name or displayName over 255 characters: a run reaching it could not save its steps. Blocking, and refused by every write; a warning for a name the definition being replaced already holds, so a workflow stored with one can still be saved and published). missing_required_config blocks only at an app’s default version: a step pinned to (or, unpinned, running) an older version gets it as a warning.
pathstring: Where in the definition the problem is, e.g. trigger.nextAction.config.body_type.
stepstring: The step’s name, when the problem belongs to a step.
fieldstring: The offending config field, when there is one.
messagestring: Human-readable explanation.
alternativesarray of strings: The admissible values at this position, nearest miss first.
moreAlternativesinteger: How many legal values were NOT listed — so you can tell a complete vocabulary from a sample. 0 or absent means alternatives is the whole set.
blockingboolean: True when a save or publish would refuse on this. Set by the validator; the informational endpoint and the write gates cannot disagree because they run the same function.
stepLabelstring
fieldLabelstring
canPublishboolean: It could be published as it would be made: false also when a chosen connection is error, expired or pending (publishBlockedBy.code: CONNECTION_NOT_WORKING). Whether the caller may publish is the caller’s own permissions.
publishBlockedByobject or null: The first thing that keeps it from being turned on; null when nothing does.
codestring: The first blocking diagnostic’s code.
messagestring
stepstring: The step it is about, as the canvas names it.
fieldstring: The field it is about, as the app titles it.
fillarray of objects: What the person is asked to fill in, in step order: worked out before the request’s values, so it stays the same while they type.
stepstring
stepLabelstring
pieceIdstring
actionIdstring
fieldstring
fieldLabelstring
propertyTypestring
requiredboolean
whystring: One of bound, check, required.
slotstring or null: The slot of the step’s connection.
value: What the workflow would get, with the request’s values applied.
hint: The old value of a blanked bound field; null otherwise.
savedHereboolean: The template was saved in this workspace.
savedInstring or null: Where it was saved (a workspace’s name; an installation template: the organization it was shared from).

Preview using a template

Parameters

Path

Body

Read it

Responses

Body

Response · 200 OK

Panel