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

# Create a workflow

`POST /api/v1/workflows`

## Request

- Base URL: `https://api.sendly.now`
- URL: `https://api.sendly.now/api/v1/workflows`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `better-auth.session_token`
  - OAuth 2 (authorization code, authorization URL `https://app.sendly.now/api/auth/oauth2/authorize`, token URL `https://app.sendly.now/api/auth/oauth2/token`, scopes: `workflows:write`)

Creates a workflow with its single trigger step. `trigger_type` defaults to `EVENT`, which requires `event_name`; `SCHEDULE` takes `interval_ms` and `MANUAL` is started only by `POST /api/v1/workflows/{id}/executions`.

Pass `sequence` to create the steps at the same time, as a LINEAR chain behind the trigger. Anything with a branch is `PUT /api/v1/workflows/{id}/graph`. Without a sequence the workflow holds only its trigger and stays inert until it has steps to run, which is why it is created disabled.

Requires the `workflows:write` scope — Create, edit, enable, and delete your automation workflows.

## Request body

- WorkflowCreateV1: Body for POST /api/v1/workflows.
  - `allow_reentry` boolean
  - `description` string
  - `enabled` boolean: Workflows are created disabled. A workflow can only be enabled once every step is configured.
  - `event_name` string: The custom event that starts this workflow, e.g. `user.signup`. Required for `EVENT` workflows (the default) and ignored for the other trigger types.
  - `interval_ms` integer: For `SCHEDULE` workflows: how often the workflow fires, in milliseconds. Between one minute and 30 days; defaults to one hour.
  - `name` string, required
  - `sequence` WorkflowSequenceStepV1[]: Optional LINEAR chain to create the workflow with, in run order. The trigger step is prepended and each step is wired to the next, so this cannot express branches — use `PUT /api/v1/workflows/{id}/graph` for those. Omit it to create a workflow that holds only its trigger step.
    - `config` object, required: Step configuration. Keys are camelCase — see `WorkflowStepV1` for the shape each step type expects.
    - `name` string, required: Human-readable label, e.g. `Day 0: welcome`.
    - `template_id` string, uuid: For `SEND_EMAIL`: a template in this project.
    - `type` 'SEND_EMAIL' | 'DELAY' | 'WAIT_FOR_EVENT' | 'CONDITION' | 'EXIT' | 'WEBHOOK' | 'UPDATE_CONTACT' | 'SEND_AT_OPTIMAL_TIME', required: A step kind that may appear in a linear `sequence`. `TRIGGER` is prepended by the server.
  - `trigger_type` 'EVENT' | 'MANUAL' | 'SCHEDULE': What starts this workflow. Defaults to `EVENT`, which is the only kind the API created before this field existed. `EVENT` requires `event_name`; `SCHEDULE` uses `interval_ms`; `MANUAL` is started only by `POST /api/v1/workflows/{id}/executions`.

## Response `201`

Workflow created

- WorkflowV1: An automation workflow as exposed on the v1 API.
  - `allow_reentry` boolean, required
  - `created_at` string, date-time, required
  - `description` string, nullable, required
  - `enabled` boolean, required
  - `event_name` string, nullable, required: Trigger event for `EVENT` workflows; null for the other trigger types.
  - `id` string, uuid, required
  - `max_executions_per_hour` integer, nullable, required
  - `name` string, required
  - `step_count` integer, required: Steps in this workflow's graph, trigger step included — so a workflow that has only ever been created reports 1. Read `/graph` for the steps themselves.
  - `trigger_type` 'EVENT' | 'MANUAL' | 'SCHEDULE', required
  - `updated_at` string, date-time, required
  - `version` integer, required: Incremented on every structural (step/transition) change.

## Other responses

- `401`: `invalid_api_key` or `invalid_session` — missing or invalid credentials.
- `403`: `scope_missing`, `project_access_denied`, or `project_disabled`.
- `422`: `validation_error` — query, path, or body parameters did not match the schema.
- `429`: `rate_limited` — see `Retry-After` and the `RateLimit` headers.
- `500`: `internal_error`.

---

[API](https://skmtc.dev/sendly/apis/sendly-api.md) · [All operations](https://skmtc.dev/sendly/apis/sendly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sendly/apis/sendly-api/revisions/ce7cfb7f7c7e?raw)