Create a new workflow from a template
workflow:writeCreates 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 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
The template's UUID. A value that is not a valid UUID answers 404, not 400.
uuidHeader Parameters
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.
length <= 255Request 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" }}Delete a template DELETE
Previous Page
Editor Internals
The operations GoRunner's own builder uses moment to moment — presence heartbeats, the test-event listener, step testing, and step-data lookups. Documented because every route the server serves is documented; an integration script will almost never need them.