Create a workflow
workflow:writeCreates a workflow. It is ALWAYS created as a draft, whatever the body says — status, webhookToken, latestVersionId, workspaceId and orgId are server-owned and ignored here; going live is POST /api/workflows/{id}/publish.
Omit definition and you get a valid empty tree with an unconfigured manual trigger, ready to be filled in with PUT /api/workflows/{id}. Supply one and it is structurally validated first (unknown keys anywhere in the tree are refused with 400 — see the FlowVersion schema), any webhookToken inside it is stripped, and every step without an explicit pieceVersion is pinned to the version the live worker fleet currently serves.
triggerType is derived from definition.trigger when you leave it out, so you normally should. Create does NOT check that the pieces you reference exist — call POST /api/workflows/validate first if you want a full report before writing.
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
Header Parameters
Opt-in replay protection, max 255 characters. Retrying with the same key replays the original response (the reply then carries Idempotency-Replayed: true) instead of creating a second workflow. The key is fingerprinted against the method, path, query string and body: reusing it with a different body returns 422. A key whose original request is still running returns 409 after a short wait. Records are kept 24 hours.
length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
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/workflows" \ -H "Content-Type: application/json" \ -d '{ "name": "Order intake" }'{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "description": "string", "definition": { "schemaVersion": 2, "trigger": { "name": "string", "displayName": "string", "type": "manual", "pieceId": "string", "pieceVersion": "string", "actionId": "string", "config": {}, "connectionId": "string", "valid": true, "nextAction": { "name": "string", "displayName": "string", "type": "PIECE", "pieceId": "string", "pieceVersion": "string", "actionId": "string", "config": {}, "connectionId": "string", "valid": true, "skip": true, "nextAction": {}, "branches": [ { "name": "string", "conditions": [ [ { "field": "string", "operator": "text_eq", "value": null } ] ], "firstAction": {} } ], "firstLoopAction": {}, "onErrorAction": {} } }, "settings": { "timeoutSeconds": 0, "errorWorkflowId": "51d8ee47-3646-4ae6-bc48-c85415c9166a", "concurrencyLimit": 0, "maintenanceMode": true, "autoPublishFixes": true }, "annotations": null, "variables": {}, "pinnedData": {} }, "status": "draft", "triggerType": "manual", "cronExpression": "string", "webhookToken": "string", "latestVersionId": "750445c5-7ad9-40bd-a593-bb37d7d846db", "definitionRev": 0, "hasUnpublishedChanges": true, "folderId": "5b6379a4-2a6c-4085-b184-45838a3b8e7e", "tags": [ "string" ], "testPayloads": {}, "pinnedData": {}, "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", "lastRun": { "status": "pending", "startedAt": "2019-08-24T14:15:22Z" } }}