Install a template
This page needs your own installation with an Embed license.
POST/
Makes a workflow in an account from a shared template, and connects each slot.
Needs a partner key: Authorization: Bearer gre_…, from Platform › Partner keys. Call it from your server only.
Parameters
Path
accountIdRequired · stringYour ID for the customer’s account: 1 to 255 bytes of UTF-8, case-sensitive. URL-encode it: it may contain
/.
Headers
Idempotency-KeyOptional · stringUp to 255 characters. The same request with the same key within 24 hours answers the first result again, with
Idempotency-Replayed: true.
Body
templateKeyRequired · stringThe template’s
key.connectionsOptional · objectEach slot’s connection:
{"c1": {"key": "sheets-main"}}for one you manage, or{"id": "…"}for one the customer made.enableOptional · booleantruealso turns it on. If it can’t be, it is made as a draft anyway.nameOptional · string1 to 200 characters. Left out: the template’s name.
workspaceIdOptional · stringThe workspace, by your ID. Left out: the default workspace.
When it can’t go live
The answer is 201 either way, so a retry with the same Idempotency-Key answers it again. publishRefusal has the {code, message} that Enable a workflow would answer. Fix it, then enable.
Responses
- 201Created
The workflow, and
install: whether it went live, why not (publishRefusal), and the slots left empty (missing). A field isn’t valid.
details.fieldnames it.- 404
NOT_FOUNDNo such account, workspace or shared template; or a slot’s connection isn’t in the workspace (
details.slot). Nothing was made. The account is deleted. Restore it first, within 30 days.
- 409
CONFLICTA request with this
Idempotency-Keyis still running. Retry shortly. A connection is for another service than its slot needs (
details.slot). Nothing was made.The template uses an app this account may not use. Nothing was made.
The template uses an app this installation’s workers don’t run. Nothing was made.
Something failed on the installation’s side. Try again.
The apps the account may use couldn’t be read. Nothing was written. Try again.
Any call can also answer: 401 UNAUTHORIZED · 403 EMBED_NOT_LICENSED · 403 IP_NOT_ALLOWED · 413 PAYLOAD_TOO_LARGE · 415 INVALID_CONTENT_TYPE · 429 RATE_LIMITED · 503 BUSY. See Errors.
Request
GORUNNER="https://automations.example.com"
GORUNNER_EMBED_KEY="YOUR_PARTNER_KEY" # gre_…
ACCOUNT_ID="acct-bakery"
URL="$GORUNNER/api/embed/v1/accounts/$ACCOUNT_ID/"
URL="${URL}workflows"
curl -X POST "$URL" \
-H "Authorization: Bearer $GORUNNER_EMBED_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"templateKey": "orders-to-sheets",
"connections": {
"c1": {
"key": "sheets-main"
}
},
"enable": true
}'const GORUNNER = "https://automations.example.com";
const KEY = process.env.GORUNNER_EMBED_KEY; // gre_…
const ACCOUNT_ID = encodeURIComponent("acct-bakery");
const res = await fetch(
`${GORUNNER}/api/embed/v1/accounts/` +
`${ACCOUNT_ID}/workflows`,
{
method: "POST",
headers: {
Authorization: `Bearer ${KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
templateKey: "orders-to-sheets",
connections: {
c1: { key: "sheets-main" },
},
enable: true,
}),
},
);
const { data } = await res.json();import os, uuid, requests
from urllib.parse import quote
GORUNNER = "https://automations.example.com"
KEY = os.environ["GORUNNER_EMBED_KEY"] # gre_…
ACCOUNT_ID = quote("acct-bakery", safe="")
res = requests.post(
f"{GORUNNER}/api/embed/v1/accounts/"
f"{ACCOUNT_ID}/workflows",
headers={
"Authorization": f"Bearer {KEY}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"templateKey": "orders-to-sheets",
"connections": {
"c1": {"key": "sheets-main"},
},
"enable": True,
},
)
data = res.json()["data"]Response · 201 Created
{
"data": {
"id": "3b1e5c2a-7d4f-4e8b-a1c6-5f2d9b0e7a31",
"name": "New orders to Sheets",
"description": "Adds each new order as a row.",
"status": "live",
"triggerType": "webhook",
"workspace": {
"id": null,
"default": true
},
"templateId": "9c4e2a17-3d5b-4f86-b0e2-8a1c7d3f5e29",
"createdAt": "2026-10-20T08:00:00Z",
"updatedAt": "2026-10-25T09:00:00Z",
"install": {
"published": true,
"publishRefusal": null,
"missing": []
}
}
}Every field
Body
templateKeyRequired · stringnameOptional · stringOmitted = the template’s name.
workspaceIdOptional · stringOmitted = the account’s default workspace (
defaultnames it too); the empty value is refused.connectionsOptional · objectSlot
key→ the connection that fills it.{key}objectEach key’s value. One of:
key, orid.keyOptional · stringThe partner’s connection key.
idOptional · UUIDA connection’s id (one the customer made).
enableOptional · booleanDefault
false.
Response · 201 Created
dataobjectidUUIDnamestringdescriptionstringstatusstringdraft: never published;live: its trigger is on;paused: published, trigger off.One of
draft,live,paused.triggerTypestringworkspaceobjectidstring or nullThe partner’s workspace id; null for the default workspace.
defaultbooleantemplateIdUUID or nullThe template it was installed from.
webhookUrlURLWhere this workflow takes deliveries (
POST /api/webhooks/{token}): on a webhook-triggered workflow, once its first publish or save has made the address, and only in the two reads,GET .../workflowsandGET .../workflows/{workflowId}(Cache-Control: no-store), never in a write’s answer, which anIdempotency-Keycan keep for a day. It takes deliveries while the workflow isliveand answers 404 otherwise. It starts production runs with no other credential: hold it as you hold this key. It stays the same across enable and disable, and changes only when a token rotates it (POST /api/workflows/{id}/webhook/rotate). Absent otherwise.createdAttimeupdatedAttimeinstallobjectpublishedbooleanpublishRefusalobject or nullWhy
enablecould not publish (null when it did, or was not asked): the same{code, message}POST …/enableanswers.codestringmessagestringmissingarray of objectsSlots left without a connection.
keystringThe slot’s name in this template (
c1,c2, … in the order the steps first use it).pieceIdstringThe service a connection for this slot must be for.
stepsarray of stringsThe steps that use it;
triggerfor the trigger.