GoRunner

Create a new workflow from a template

Requires scope workflow:write
POST
/api/templates/{id}/use

Creates a brand-new workflow in the caller's WORKSPACE from an org template. The template is unchanged, and the two are not linked afterwards.

The new workflow is always a DRAFT: it has no published version and no trigger goes live until you publish it separately. description and triggerType are copied from the template.

BODY IS OPTIONAL. Send {"name": "..."} to override the name; send nothing (or a blank name) and the template's own name is used. A resolved name over 255 characters is a 400.

CONNECTION REFERENCES ARE RESOLVED AGAINST THIS WORKSPACE. Connections are workspace-scoped, so a template saved elsewhere can carry connectionIds that mean nothing here. Every reference this workspace cannot resolve is CLEARED (set to null) and that step is marked valid: false, so the new workflow arrives visibly incomplete rather than looking wired to something that resolves to nothing at run time. Expect to re-attach connections (by id) after using a cross-workspace template. The clearing walks the trigger, every action, branch arms, loop bodies and error arms.

PIECE VERSIONS: the snapshot keeps whatever version pins the source flow had; only steps that were never pinned pick up the fleet's current version. If the template references a piece — or a pinned piece VERSION — this instance's worker fleet cannot run, the call is refused 422 rather than minting a workflow whose steps would fail at run time.

Accepts Idempotency-Key, so a retry after a dropped connection replays the first response instead of creating a second workflow.

Authorization

bearerAuth
AuthorizationBearer <token>

An API token: Authorization: Bearer grt_…. Mint one in the app under Settings → Workspace → API tokens; the raw value is shown once. Scopes confine the token — see x-permission on each operation.

In: header

Path Parameters

id*string

The template's UUID. A value that is not a valid UUID answers 404, not 400.

Formatuuid

Header Parameters

Idempotency-Key?string

Optional opt-in de-duplication key, 255 characters max. Retrying with the SAME key and the same method + path + query + body replays the first response verbatim without creating a second workflow, and the replay carries the response header Idempotency-Replayed: true. Records live 24 hours. The same key with a DIFFERENT request is refused 422; a duplicate arriving while the first is still running is answered 409 after a short wait. Only successful writes are recorded. Use a fresh UUID per logical operation.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Optional body. Send nothing at all to use the template's own name.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/templates/497f6eca-6276-4993-bfeb-53cbbbba6f08/use" \  -H "Idempotency-Key: 7c1f5b6a-4f4b-4a8a-9c1e-9c2f3a5d7e11" \  -H "Content-Type: application/json" \  -d '{    "name": "Order intake — EU"  }'
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "description": "string",    "definition": {      "schemaVersion": 2,      "trigger": {},      "variables": {},      "settings": {}    },    "status": "draft",    "triggerType": "string",    "webhookToken": "string",    "folderId": "5b6379a4-2a6c-4085-b184-45838a3b8e7e",    "tags": [      "string"    ],    "hasUnpublishedChanges": true,    "workspaceId": "ef0efa32-d1c1-43d4-a5e2-fe7b4f00403c",    "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",    "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}