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

# Create a new workflow definition

`POST /api/v1/workflows`

## Request

- Base URL: `https://api.korala.ai`
- URL: `https://api.korala.ai/api/v1/workflows`
- Auth: one of:
  - API key in header `X-API-Key`
  - `bearer` (a scheme the document does not define)

## Headers

- `X-Korala-Mode` 'live' | 'test'

## Request body

- CreateWorkflowDefinitionDto
  - `outputSharing` WorkflowOutputSharingRuleDto[]: Outputs restricted to the journey that starts this verification, including outputs of later steps in this workflow. Independent fields in the same step remain shared. An empty array clears restrictions.
    - `stepIndex` number, required
    - `stepType` string: Physical step type, or workflow for its approval result.
    - `field` string, required: A verification field alias or output field path.
    - `scope` 'current_context', required
  - `name` string, required
  - `slug` string, required
  - `description` string
  - `steps` string[], required: Array of step configurations
  - `inputSchema` object: Expected input schema (JSON Schema format)
  - `outputSchema` object: Expected output schema (JSON Schema format)
  - `isPublic` boolean: Whether this workflow is publicly accessible for demos

## Response `201`

- ManagedWorkflowDefinitionDto
  - `sandbox` boolean, required: Persisted execution mode: true for test data
  - `id` string, required
  - `organizationId` string, nullable
  - `name` string, required
  - `slug` string, required
  - `description` string, nullable
  - `steps` WorkflowStepDto[], required
    - `type` 'capture' | 'ocr' | 'extract' | 'validate' | 'enrich' | 'check' | 'risk' | 'output' | 'review' | 'webhook', required
    - `config` object, required
  - `inputSchema` object, nullable
  - `outputSchema` object, nullable
  - `isPublic` boolean, required
  - `isActive` boolean, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required: When what a run executes last changed: the steps, output sharing, the input or output schema, or the slug. A rename, a new description or switching the workflow on or off leaves it alone.
  - `outputSharing` WorkflowOutputSharingRuleDto[], required
    - `stepIndex` number, required
    - `stepType` string: Physical step type, or workflow for its approval result.
    - `field` string, required: A verification field alias or output field path.
    - `scope` 'current_context', required

---

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