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

# Create a workflow

`POST /workflows`

Creates a workflow in the caller's org. Name must match ^[A-Za-z0-9_-]+$ and be unique within the org. Pass code to save the workflow's first code revision atomically with it; omit it to create an empty workflow and add code later. Returns the workflow_id (plus revision_id and revision when code was provided).

## Request body

- WorkflowCreateRequest — Request body for creating a new workflow.
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `capture` boolean — Capture media this workflow's runs produce on the phone into the org's file library (default true). false disables capture for every run dispatched through the scheduler.
  - `code` string — Optional Python source for the workflow's first revision, saved atomically with the workflow when provided.
  - `name` string, required — Human-readable workflow name.
  - `ocr_engine` 'free' | 'premium' — OCR backend to use.
  - `platform` 'ios' | 'android' | 'both' — Target OS platform.
  - `recording` boolean — Record this workflow's runs (default true). false suppresses video recording and the rolling thumbnail entirely, for every run dispatched through the scheduler.
  - `telemetry` boolean — Persist telemetry spans for this workflow's runs (default true). false skips the durable trace store; the live telemetry stream still works while a run is active.

## Response `201`

Created

- WorkflowCreateResponse — Returned after successfully creating a workflow.
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `revision` integer — Revision number of the first code revision (1), when code was provided.
  - `revision_id` string — Id of the first code revision, when code was provided.
  - `workflow_id` string, required — Identifier assigned to the new workflow.

## Other responses

- `default` — Error

## Changes

> 18 revisions in range; 8 could not be searched.

- **2026-07-18** `80c0e071bf67` — 2 breaking, 5 info
  - request property `ocr_engine` was restricted to a list of enum values
  - request property `platform` was restricted to a list of enum values
  - added the new `android` enum value to the request property `platform`
  - added the new `both` enum value to the request property `platform`
  - …3 more
- **2026-07-03** `5ae84ace57ac` — 1 warning, 3 info
  - removed the request property `goal`
  - added the new optional request property `code`
  - added the optional property `revision` to the response with the `201` status
  - added the optional property `revision_id` to the response with the `201` status
- **2026-06-29** `206b42a858c3` — 1 info
  - api operation id `workflow-create` removed and replaced with `workflows_create`

[Change history](https://skmtc.dev/axilioai/apis/axilio-api/changes/workflows/post.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api.md) · [All operations](https://skmtc.dev/axilioai/apis/axilio-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/axilioai/axilio-api/revisions/8a66f81813b3/schema)