Skip to main content
GET/workflows

List Workflows

Returns the paginated list of workflows in the specified project, ordered by authored date descending.

Accessible to all Forge, Studio, and Workspace cohort roles subject to RLS; no PROJECT_AUTHOR role required for read access.

Parameters
statusquery

Return only workflows with this status.

Omit it for every status.

limitquery

How many workflows to return, 1 to 100 (a larger number is treated as 100).

Default 25.

cursorquery

meta.cursor.next from the previous page.

Omit it for the first page.

projectSlug *path

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

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
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_DENIEDYour role does not include any Forge, Studio, or Workspace cohort permission required to list workflows.
Response body (200)
data *object[]

The project's workflows, newest first.

When more match, meta.cursor.next holds the cursor for the next page; otherwise it is null.

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.

meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.studio.workflows.list()

Showing example in TypeScript

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

More in Compute & Automation