GoRunner docs
Search or askSearch⌘K

Install a template

POST/api/embed/v1/accounts/{accountId}/workflows

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.

Embed · Self-hosted with an Embed license

Parameters

Path

accountIdRequired · string

Your ID for the customer’s account: 1 to 255 bytes of UTF-8, case-sensitive. URL-encode it: it may contain /.

Headers

Idempotency-KeyOptional · string

Up to 255 characters. The same request with the same key within 24 hours answers the first result again, with Idempotency-Replayed: true.

Body

templateKeyRequired · string

The template’s key.

connectionsOptional · object

Each slot’s connection: {"c1": {"key": "sheets-main"}} for one you manage, or {"id": "…"} for one the customer made.

enableOptional · boolean

true also turns it on. If it can’t be, it is made as a draft anyway.

nameOptional · string

1 to 200 characters. Left out: the template’s name.

workspaceIdOptional · string

The 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.field names it.

  • No 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.

  • A request with this Idempotency-Key is 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
  }'

Response · 201 Created

json
{
  "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 · string
nameOptional · string

Omitted = the template’s name.

workspaceIdOptional · string

Omitted = the account’s default workspace (default names it too); the empty value is refused.

connectionsOptional · object

Slot key → the connection that fills it.

{key}object

Each key’s value. One of: key, or id.

keyOptional · string

The partner’s connection key.

idOptional · UUID

A connection’s id (one the customer made).

enableOptional · boolean

Default false.

Response · 201 Created

dataobject
idUUID
namestring
descriptionstring
statusstring

draft: never published; live: its trigger is on; paused: published, trigger off.

One of draft, live, paused.

triggerTypestring
workspaceobject
idstring or null

The partner’s workspace id; null for the default workspace.

defaultboolean
templateIdUUID or null

The template it was installed from.

webhookUrlURL

Where 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 .../workflows and GET .../workflows/{workflowId} (Cache-Control: no-store), never in a write’s answer, which an Idempotency-Key can keep for a day. It takes deliveries while the workflow is live and 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.

createdAttime
updatedAttime
installobject
publishedboolean
publishRefusalobject or null

Why enable could not publish (null when it did, or was not asked): the same {code, message} POST …/enable answers.

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.