---
title: "Create a workflow"
method: POST
path: "/api/workflows/"
tags: ["workflows"]
---

# Create a workflow

`POST /api/workflows/`

Create a new workflow family with an editable draft. Task IDs and sequential links are generated when omitted. `type` defaults to `automations`; deployment and read-only state are server controlled.

## Headers

- `Authorization` string, required

## Request body

- object
  - `name` string, nullable
  - `description` string, nullable
  - `type` 'automations' | 'monitors' | 'evaluators' | 'reports' | 'exports' | 'ingests' — Workflow category. Defaults to `automations`.
  - `trigger_event_type` 'request_log' | 'trace_completed' | 'customer_budget_limit_reached' | 'credit_low_balance_threshold_reached' | 'spend_cap_warning_threshold_reached' | 'limit_policy_soft_triggered' | 'limit_policy_hard_triggered' | 'on_eval_result_ingested' | 'custom_event' | 'eval_only' | 'scheduled' — Event that triggers the workflow. Use `scheduled` with `schedule_cron`.
  - `schedule_cron` string, nullable — UTC five-field cron expression. Required when `trigger_event_type` is `scheduled`, forbidden for other trigger types, and limited to a minimum five-minute cadence. Timezone prefixes such as `TZ` and `CRON_TZ` are not supported.
  - `is_starred` boolean
  - `tasks` ApiWorkflowsPostRequestBodyContentApplicationJsonSchemaTasksItems[]
    - `id` string — Stable task ID. The server generates one when omitted.
    - `type` string, required
    - `label` string, nullable
    - `next` union — ID or IDs of the next task. Sequential links are generated when omitted.
      - string
      - string[]
    - `config` object

## Response `201`

Workflow draft created.

- WorkflowsCreateWorkflowResponse201
  - `id` string, required
  - `workflow_id` string, required
  - `version` integer, required
  - `name` string, nullable
  - `description` string, nullable
  - `version_description` string — Commit message for this version. Set only through the commit endpoint.
  - `type` 'automations' | 'monitors' | 'evaluators' | 'reports' | 'exports' | 'ingests', required — Workflow category. Defaults to `automations`.
  - `trigger_event_type` 'request_log' | 'trace_completed' | 'customer_budget_limit_reached' | 'credit_low_balance_threshold_reached' | 'spend_cap_warning_threshold_reached' | 'limit_policy_soft_triggered' | 'limit_policy_hard_triggered' | 'on_eval_result_ingested' | 'custom_event' | 'eval_only' | 'scheduled' — Event that triggers the workflow. Use `scheduled` with `schedule_cron`.
  - `schedule_cron` string, nullable — UTC five-field cron expression. Required when `trigger_event_type` is `scheduled`, forbidden for other trigger types, and limited to a minimum five-minute cadence. Timezone prefixes such as `TZ` and `CRON_TZ` are not supported.
  - `is_enabled` boolean, required
  - `is_starred` boolean
  - `is_read_only` boolean, required
  - `is_public` boolean
  - `unique_organization_id` string, nullable
  - `has_async_steps` boolean
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `deployed_version` integer, nullable
  - `tags` ApiWorkflowsPostResponsesContentApplicationJsonSchemaTagsItems[]
    - `id` string, required
    - `name` string, required
    - `color` string, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `tasks` ApiWorkflowsPostResponsesContentApplicationJsonSchemaTasksItems[], required
    - `id` string — Stable task ID. The server generates one when omitted.
    - `type` string, required
    - `label` string, nullable
    - `next` union — ID or IDs of the next task. Sequential links are generated when omitted.
      - string
      - string[]
    - `config` object
  - `graph` ApiWorkflowsPostResponsesContentApplicationJsonSchemaGraph
    - `node_count` integer
    - `edge_count` integer
    - `entry_nodes` string[]
    - `terminal_nodes` string[]
    - `nodes` object

## Other responses

- `400` — Invalid request.
- `401` — Authentication failed.

---

[API](https://skmtc.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/revisions/4e064cf81dae/schema)