Make a workflow from a template

POST/api/templates/{id}/use

Makes a new workflow in this workspace from a template.

Needs an API token with the Write permission for workflows (workflow:write).

Parameters

Path

idRequired · UUID: The template’s ID.

Headers

Idempotency-KeyOptional · string: Up to 255 characters. The same request with the same key within 24 hours answers the first result again, instead of making a second workflow.

Body

Optional. Nothing makes a draft named after the template.

nameOptional · string: Up to 255 characters, trimmed. Blank: the template’s name.
connectionsOptional · object: A connection of this workspace for each slot: {"c1": "…"}. It must be for the slot’s service.
valuesOptional · object: Fill-ins, by step name and field: {"step": {"field": value}}. A step or field the template lacks is refused.
publishOptional · boolean: true turns the workflow on when it can run, as Publish a workflow does. Needs the Publish permission.
folderIdOptional · UUID or null: A folder of this workspace to file it in.

Connections, by slot

A template needs one connection for each service account its steps use: its slots, c1, c2… Preview using it lists them with the connections that could fill each.

A slot you don’t name keeps the template’s own connection where it exists here. Otherwise its steps arrive without one, and install.missing lists the slot.

When publish is refused

A refused turn-on is not an error. The draft is made, the answer is still 201, and install.publishRefusal says why: CONNECTION_NOT_WORKING when a chosen connection isn’t working, or what Publish a workflow would answer.

A value tied to the account the template was saved with, such as a choice filled from it, arrives blank outside the workspace it was saved in. An expression never does.

Responses

201Created
The new workflow, a draft or live, and install: what was done.
400VALIDATION_ERROR
The body isn’t JSON, the name is over 255 characters, connections names a slot the template lacks or a connection outside the workspace, folderId isn’t a folder here, values names a step or field the template lacks, the template holds a condition operator that doesn’t exist or a step name or display name over 255 characters, or Idempotency-Key is over 255 characters.
403FORBIDDEN
The token lacks the Write permission for workflows, or publish is true without Publish. Nothing is made.
403FEATURE_OFF
A token made inside a partner’s product, with the publish or folders switch off (details.switch).
403ACCOUNT_SUSPENDED
The workspace’s account is suspended. Nothing is made.
404NOT_FOUND
No template with this ID that this workspace may use. An ID that isn’t a UUID answers this too.
409CONFLICT
A request with this Idempotency-Key is still in progress, or its answer was too large to keep.
409ACCOUNT_DELETED
The workspace’s account was deleted.
422VALIDATION_ERROR
The template uses an app, or an app version, this installation can’t run.
422VALIDATION_ERROR
This Idempotency-Key was already used with a different request.
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).
500INTERNAL_ERROR
The template or the workspace’s connections couldn’t be read, or the workflow couldn’t be made.
503STATE_UNAVAILABLE
The account’s state couldn’t be read. Nothing was made.
503PIECES_UNAVAILABLE
GoRunner couldn’t check which apps this workspace may use. Nothing was made.

Any call can also answer: 401 UNAUTHORIZED · 401 TOKEN_ENDED · 403 TOKEN_SURFACE_OFF · 403 EMBED_NOT_ALLOWED · 403 EMBED_NOT_AVAILABLE · 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 Write for workflows
TEMPLATE_ID="your-template-id"

curl -X POST "$GORUNNER/api/templates/$TEMPLATE_ID/use" \
  -H "Authorization: Bearer $GORUNNER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order intake — EU",
    "connections": {
      "c1": "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b"
    },
    "publish": true
  }'

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`,
  {
    method: "POST",
    headers: {
        Authorization: `Bearer ${TOKEN}`,
        "Idempotency-Key": crypto.randomUUID(),
        "Content-Type": "application/json",
      },
    body: JSON.stringify({
        name: "Order intake — EU",
        connections: {
          c1: "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b",
        },
        publish: true,
      }),
  },
);
const { data } = await res.json();

import os, uuid, 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",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "name": "Order intake — EU",
      "connections": {
        "c1": "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b",
      },
      "publish": True,
    },
)
data = res.json()["data"]

Response · 201 Created, shortened

json

{
  "data": {
    "id": "6e9a1c3f-8b2d-4a57-9e0c-3f7b5d1a8c42",
    "name": "Order intake — EU",
    "status": "active",
    "triggerType": "webhook",
    "webhookToken": "2f4c8e1a-6b3d-4f7e-9a05-c1d2e3f4a5b6",
    "install": {
      "published": true,
      "publishRefusal": null,
      "missing": []
    }
  }
}

Every field

Body

nameOptional · string

Optional name for the new workflow; trimmed. Blank or absent uses the template’s name. Max 255 characters.

connectionsOptional · object

Slot key → a connection of this workspace made for the slot’s service.

{key}UUID

Each key’s value.

publishOptional · boolean

Turn the new workflow on when it can run. Needs workflow:publish. A refused turn-on keeps the draft and is reported in install.publishRefusal.

Default false.

folderIdOptional · UUID or null

A folder of this workspace to file the new workflow in.

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 · 201 Created

dataobject

The workflow created from a template — the same shape the workflows API returns — and what the install did.

idUUID

namestring

descriptionstring

Copied from the template.

definitionobject

The template’s snapshot with its connection slots filled (steps of a slot left empty, and any other connection this workspace cannot resolve, carry no connection), and previously-unpinned steps on the fleet’s current app versions.

A workflow definition: its fields are in Workflow definition.

statusstring

draft, or active when publish turned it on.

One of draft, active, paused.

triggerTypestring

Copied from the template.

webhookTokenstring

Present for a webhook workflow that publish turned on: the secret segment of the public webhook URL. Treat it as a credential.

folderIdUUID

The folder it was filed in, when folderId was sent.

tagsarray of strings

hasUnpublishedChangesboolean

workspaceIdUUID

orgIdUUID

createdByUUID

createdAttime

updatedAttime

installobject

What using the template did, beside the workflow it made.

publishedboolean

The new workflow was turned on.

publishRefusalobject or null

Why publish did not publish it: CONNECTION_NOT_WORKING when a chosen connection is error, expired or pending (the workflow is made as a draft), else the {code, message} POST /api/workflows/{id}/publish answers (VALIDATION_ERROR, PIECE_NOT_ALLOWED, PIECES_UNAVAILABLE). null when it did, or was not asked.

codestring

messagestring

missingarray of objects

Slots left without a connection.

keystring

The slot’s name in this template (c1, c2, … in the order the steps first use it).

pieceIdstring

The service a connection for this slot must be for.

stepsarray of strings

The steps that use it; trigger for the trigger.

latestVersionIdUUID or null

Present when publish turned it on: the published version.

definitionRevinteger

Present when publish turned it on.

testPayloadsobject or null

Present, null, when publish turned it on.

Make a workflow from a template

Parameters

Path

Headers

Body

Connections, by slot

When publish is refused

Responses

Body

Response · 201 Created

Panel