/workflowsCreate Workflow
Creates a new workflow in the project with a name, trigger type (one of view_row_event, form_submission, scheduled, manual, or webhook), trigger configuration, and an ordered actions chain of up to 9 action types.
Requires the PROJECT_AUTHOR role.
Errors:
K9O_WORKFLOW_TRIGGER_INVALID(400) if thetrigger_configshape is incompatible with the declaredtrigger_type.K9O_WORKFLOW_ACTION_INVALID(400) if any step in theactionschain is malformed or contains a cycle.400 K9O_INVALID_FIELD_VALUEnaming the field, for an invalid expression or timezone.
A scheduled trigger's triggerConfig.scheduleExpression is standard 5-field cron (values, lists, ranges, steps, month and day names; day-of-week 0-7, Sunday is 0 or 7) or an alias such as @daily.
It is read in triggerConfig.timezone (an IANA name; default UTC).
Runs must be at least 5 minutes apart.
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| name * | string | The workflow's name, unique in the project. |
| description | string | What the workflow does. Default empty. |
| status | "active" | "archived" | "draft" |
Default |
| triggerType * | "view_row_event" | "form_submission" | "scheduled" | "manual" | "webhook" | What starts a run: |
| triggerConfig * | any | The trigger's settings, an object. Its shape depends on
|
| actions * | object[] | The steps, in order: up to 50 at the top level and 100 in all, counting branches. A draft may have none. |
| index * | integer | The step's position in the chain, from 0. |
| action_type * | "write_collection" | "read_collection" | "invoke_function" | "invoke_extension" | "llm_inference" | "send_notification" | "http_request" | "approval_step" | "branch" | What the step does. |
| config * | any | The step's settings. Their shape depends on
|
| retry | any | Retries for a failed step: Only steps that are safe to repeat accept it. |
| condition | any | A JSON predicate; the step runs only when it holds and is skipped otherwise. Templates may fill its values. |
| parallel | boolean | Run this step at the same time as the adjacent steps that also set it. A step that waits for approval can't be parallel. |
| rbacBinding | any | Free-form access metadata stored with the workflow and returned as sent. Default |
| HTTP | K9O Code | Description |
|---|---|---|
| 201 | Created | |
| 400 | K9O_WORKFLOW_TRIGGER_INVALID | The trigger_config shape is invalid for the declared trigger_type — required fields are missing or the configuration is malformed. |
| 400 | K9O_WORKFLOW_ACTION_INVALID | The actions chain is malformed — actions is not an array, or a step names an unknown action type. |
| 400 | K9O_INVALID_FIELD_VALUE | A scheduled trigger's `scheduleExpression` is not valid cron, or runs less than 5 minutes apart (field schedule_expression), or its `timezone` is not an IANA name (field triggerConfig.timezone). |
| 401 | K9O_INVALID_CREDENTIALS | The request was made without a valid session or bearer token. |
| 401 | K9O_SESSION_EXPIRED | Your session has expired; re-authenticate and retry. |
| 403 | K9O_ACCESS_DENIED | Creating a workflow requires the PROJECT_AUTHOR role; your current role does not grant it. |
| data * | object | The workflow as saved, plus |
| id * | string | The workflow id ( |
| projectId * | string | The project the workflow belongs to ( |
| name * | string | The workflow's name. |
| description * | string | What the workflow does. Empty when none was given. |
| status * | "active" | "archived" | "draft" |
|
| triggerType * | "view_row_event" | "form_submission" | "scheduled" | "manual" | "webhook" | What starts a run. |
| triggerConfig * | object | The trigger's settings, an object. Its shape depends on
The webhook signing secret is never part of it. |
| actions * | object[] | The steps, in order. |
| index * | integer | The step's position in the chain, from 0. |
| action_type * | string | What the step does: |
| config * | any | The step's settings. Their shape depends on
|
| retry | any | The step's retry settings, |
| condition | any | The predicate that decides whether the step runs, when set. |
| parallel | boolean | Whether the step runs alongside adjacent parallel steps, when set. |
| rbacBinding * | any | Free-form access metadata stored with the workflow and returned as sent. Default |
| authoredBy * | string | Who created the workflow ( |
| authoredAt * | string <date-time> | When the workflow was created. |
| updatedBy * | string | Who last changed the workflow ( |
| updatedAt * | string <date-time> | When the workflow last changed. |
| webhookSecret | string | The webhook signing secret ( Present only in the response that issued it: creating a Store it now; it is never shown again. |
| meta * | any |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.studio.workflows.create({
name: 'My Resource',
description: 'A description',
status: 'active',
triggerType: 'view_row_event',
triggerConfig: null,
actions: [{
index: 0,
action_type: 'write_collection',
config: null,
retry: null
}]
})Showing example in TypeScript
{
"name": "My Resource",
"description": "A description",
"status": "active",
"triggerType": "view_row_event",
"triggerConfig": null,
"actions": [
{
"index": 0,
"action_type": "write_collection",
"config": null,
"retry": null
}
]
}{
"data": {
"id": "string",
"projectId": "string",
"name": "string",
"description": "string",
"status": "active",
"triggerType": "view_row_event",
"actions": [
{
"index": 0,
"action_type": "string",
"parallel": false
}
],
"authoredBy": "string",
"authoredAt": "string",
"updatedBy": "string",
"updatedAt": "string",
"webhookSecret": "string"
}
}