---
title: "Create an automation (paused draft)"
method: POST
path: "/api/v1/automations"
tags: ["automations"]
---

# Create an automation (paused draft)

`POST /api/v1/automations`

## Request

- Base URL: `https://app.blueticked.com`
- URL: `https://app.blueticked.com/api/v1/automations`
- Auth: HTTP bearer

Instantiate a recipe as a PAUSED automation for a human to review and activate in the dashboard.

Pass `recipe_id` (either/or), or a free-form `definition` object (`{ filters: [], actions: [], … }`, the same JSON the dashboard builder edits) plus `channel` (`whatsapp`, `sms` or `email`). Free-form definitions run the full validator and are rejected with the fix list on 422.

That 422 is the one answer here outside the Error envelope: `{ "ok": false, "error": "invalid_definition", "detail": [ ... ] }`, where `detail` is a list of sentences, one for each thing to fix in the definition. Branch on `error` being the string "invalid_definition".

With `recipe_id`, pass `api_events: ["your.event"]` to replace the recipe's listening list with YOUR event names. Without it a recipe listens for its example event forever: an automation that looks wired and can never fire.

`enabled` is forced FALSE regardless of input. Nothing created here can message a customer until a human flips it live.

An SMS `send_message` step may carry `smsMessageType`: `marketing` for a promotional text, `transactional` for an order or service update. A marketing SMS goes only to contacts who opted in to SMS marketing, and only in the SMS sending hours (Mon-Fri 08:00-20:00, Sat 09:00-13:00, never Sundays or public holidays, or narrower in the workspace's SMS settings). When it is absent the step goes as transactional, except in a run started by `commerce.order.abandoned` (a basket win-back is promotional), where it goes as marketing; send it to say which. Any other value is ignored. WhatsApp and email steps do not read it.

Multi-business workspaces must pass `business_id`; single-business ones may omit it.

`automations:write` is part of the agent Prepare profile precisely because of this draft-only guarantee.

## Request body

- union
  - object
    - `recipe_id` string, required
    - `definition` object
    - `channel` 'whatsapp' | 'sms' | 'email'
    - `name` string
    - `business_id` string, uuid
    - `api_events` string[]
  - object
    - `recipe_id` string
    - `definition` object, required
    - `channel` 'whatsapp' | 'sms' | 'email'
    - `name` string
    - `business_id` string, uuid
    - `api_events` string[]

## Response `201`

Success

- object
  - `ok` boolean, required
  - `automation` object, required
    - `managed_by` string, nullable, required
    - `created_at` string, date-time, required
    - `definition` object, required
    - `id` string, uuid, required
    - `business_id` string, uuid, nullable, required
    - `name` string, required
    - `channel` 'whatsapp' | 'sms' | 'email', required
    - `trigger_type` string, required
    - `status` string, required
    - `run_count` number, required
    - `last_run_at` string, date-time, nullable, required
    - `priority` number, required
    - `updated_at` string, date-time, required
  - `note` string, required

## Other responses

- `400`: Validation failed
- `401`: Unauthorized: missing or invalid API key
- `402`: Insufficient wallet balance
- `403`: Forbidden: scope, plan limit, or suspension
- `404`: Not found
- `409`: Conflict (idempotency-key reuse or resource in use)
- `413`: Request body above the endpoint's size limit
- `422`: Understood but refused: the request is well-formed, the action is not permitted for this resource
- `429`: Rate limited
- `500`: Internal error
- `502`: An upstream provider refused or failed the request
- `503`: Channel or send queue unavailable

---

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