Skip to main content
POST/workflows

Create 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 the trigger_config shape is incompatible with the declared trigger_type.
  • K9O_WORKFLOW_ACTION_INVALID (400) if any step in the actions chain is malformed or contains a cycle.
  • 400 K9O_INVALID_FIELD_VALUE naming 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.

Parameters
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
name *string

The workflow's name, unique in the project.

descriptionstring

What the workflow does.

Default empty.

status"active" | "archived" | "draft"

draft never runs. active runs when its trigger fires and must have at least one step. archived is kept but never runs.

Default draft.

triggerType *"view_row_event" | "form_submission" | "scheduled" | "manual" | "webhook"

What starts a run: manual (the runs endpoint), webhook (a signed HTTP call), scheduled (a cron expression) or form_submission (an accepted form submission). view_row_event is refused.

triggerConfig *any

The trigger's settings, an object.

Its shape depends on triggerType:

  • manual: {}.
  • webhook: {signatureScheme?}; the only scheme is hmac-sha256. Don't send a secret: the platform generates one and returns it once, as webhookSecret.
  • scheduled: {scheduleExpression, timezone?}: a 5-field cron expression or alias, at least 5 minutes apart, read in an IANA time zone (default UTC).
  • form_submission: {extensionId, formId, collection, statuses?} for an extension's form, or {publicationId} for a published form.
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 action_type:

  • write_collection: {collection, op, payload?, filter?}. op is insert, update or delete; payload maps columns to values; filter maps columns to <operator>.<value> strings, such as {"id": "eq.{{trigger.id}}"}.
  • read_collection: {collection, filter?, select?, order?, limit}.
  • invoke_function: {functionName, payload?}.
  • invoke_extension: {extensionSlug, action, payload?}. The payload must fit the action's declared config schema.
  • llm_inference: {model, prompt, maxTokens?, temperature?}.
  • send_notification: {channel, recipient, payload?}, with channel email or webhook.
  • http_request: {url, method, headers?, query?, body?}. A GET takes no body.
  • approval_step: {approverResolver, resolverConfig, timeoutSecondsBeforeAutoFail?}, with approverResolver role, group or explicit_users. The run waits for the approvers; a timeout fails the run.
  • branch: {condition, true_branch, false_branch}, two nested step lists, up to 3 levels deep.

{{...}} templates fill values from the trigger and earlier steps; keys, collection names and operators are always literal.

retryany

Retries for a failed step: {maxAttempts, backoffStrategy?}, with maxAttempts 1 to 10 and backoffStrategy exponential (default) or fixed.

Only steps that are safe to repeat accept it.

conditionany

A JSON predicate; the step runs only when it holds and is skipped otherwise.

Templates may fill its values.

parallelboolean

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.

rbacBindingany

Free-form access metadata stored with the workflow and returned as sent.

Default {}.

Responses
HTTPK9O CodeDescription
201Created
400K9O_WORKFLOW_TRIGGER_INVALIDThe trigger_config shape is invalid for the declared trigger_type — required fields are missing or the configuration is malformed.
400K9O_WORKFLOW_ACTION_INVALIDThe actions chain is malformed — actions is not an array, or a step names an unknown action type.
400K9O_INVALID_FIELD_VALUEA 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).
401K9O_INVALID_CREDENTIALSThe request was made without a valid session or bearer token.
401K9O_SESSION_EXPIREDYour session has expired; re-authenticate and retry.
403K9O_ACCESS_DENIEDCreating a workflow requires the PROJECT_AUTHOR role; your current role does not grant it.
Response body (201)
data *object

The workflow as saved, plus webhookSecret when this response issued one.

id *string

The workflow id (wfl_...).

projectId *string

The project the workflow belongs to (proj_...).

name *string

The workflow's name.

description *string

What the workflow does.

Empty when none was given.

status *"active" | "archived" | "draft"

draft never runs. active runs when its trigger fires and must have at least one step. archived is kept but never runs.

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 triggerType:

  • manual: {}.
  • webhook: {signatureScheme?}; the only scheme is hmac-sha256. Don't send a secret: the platform generates one and returns it once, as webhookSecret.
  • scheduled: {scheduleExpression, timezone?}: a 5-field cron expression or alias, at least 5 minutes apart, read in an IANA time zone (default UTC).
  • form_submission: {extensionId, formId, collection, statuses?} for an extension's form, or {publicationId} for a published form.

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: write_collection, read_collection, invoke_function, invoke_extension, llm_inference, send_notification, http_request, approval_step or branch.

config *any

The step's settings.

Their shape depends on action_type:

  • write_collection: {collection, op, payload?, filter?}. op is insert, update or delete; payload maps columns to values; filter maps columns to <operator>.<value> strings, such as {"id": "eq.{{trigger.id}}"}.
  • read_collection: {collection, filter?, select?, order?, limit}.
  • invoke_function: {functionName, payload?}.
  • invoke_extension: {extensionSlug, action, payload?}. The payload must fit the action's declared config schema.
  • llm_inference: {model, prompt, maxTokens?, temperature?}.
  • send_notification: {channel, recipient, payload?}, with channel email or webhook.
  • http_request: {url, method, headers?, query?, body?}. A GET takes no body.
  • approval_step: {approverResolver, resolverConfig, timeoutSecondsBeforeAutoFail?}, with approverResolver role, group or explicit_users. The run waits for the approvers; a timeout fails the run.
  • branch: {condition, true_branch, false_branch}, two nested step lists, up to 3 levels deep.

{{...}} templates fill values from the trigger and earlier steps; keys, collection names and operators are always literal.

retryany

The step's retry settings, {maxAttempts, backoffStrategy?}, when set.

conditionany

The predicate that decides whether the step runs, when set.

parallelboolean

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 (usr_...).

authoredAt *string <date-time>

When the workflow was created.

updatedBy *string

Who last changed the workflow (usr_...).

updatedAt *string <date-time>

When the workflow last changed.

webhookSecretstring

The webhook signing secret (whsec_...).

Present only in the response that issued it: creating a webhook workflow, or changing one to webhook.

Store it now; it is never shown again.

meta *any
TypeScript
// 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

Request example
{
  "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
    }
  ]
}
Response example (201)
{
  "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"
  }
}

More in Compute & Automation