> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eachlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Workflow

> Create a new workflow with an initial version.

## Endpoint

```
POST https://workflows.eachlabs.run/api/v1/workflows
```

<Warning>
  This public URL uses a deprecated compatibility host outside the api-service host. It remains supported for now, but will soon move under `https://api.eachlabs.ai`. Keep integrations configurable and switch to the api-service URL once it is published.
</Warning>

## Request Body

| Field         | Type      | Required | Description                                     |
| ------------- | --------- | -------- | ----------------------------------------------- |
| `name`        | string    | Yes      | Human-readable workflow name                    |
| `description` | string    | Yes      | What the workflow does                          |
| `categories`  | string\[] | No       | Category slugs for organization                 |
| `locked`      | boolean   | No       | Lock from modifications (default: `false`)      |
| `production`  | boolean   | No       | Mark as production (default: `false`)           |
| `definition`  | object    | Yes      | Workflow definition with steps and input schema |

### Definition Object

| Field          | Type   | Description                                |
| -------------- | ------ | ------------------------------------------ |
| `version`      | string | Version identifier (e.g., `"v1"`)          |
| `steps`        | array  | Array of step definitions                  |
| `input_schema` | object | JSON Schema for workflow inputs            |
| `metadata`     | object | Additional metadata (e.g., output mapping) |

## Code Examples

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://workflows.eachlabs.run/api/v1/workflows \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "name": "Text to Image Generator",
      "description": "Generates images from text prompts using AI models",
      "categories": ["image-generation"],
      "definition": {
        "version": "v1",
        "input_schema": {
          "type": "object",
          "required": ["prompt"],
          "properties": {
            "prompt": {"type": "string", "description": "Text prompt"}
          }
        },
        "steps": [
          {
            "step_id": "generate",
            "type": "model",
            "model": "flux-1-1-pro",
            "params": {
              "prompt": "{{inputs.prompt}}"
            }
          }
        ]
      }
    }'
  ```

  ```python Python theme={"dark"}
  import requests

  response = requests.post(
      "https://workflows.eachlabs.run/api/v1/workflows",
      headers={
          "Content-Type": "application/json",
          "X-API-Key": "YOUR_API_KEY"
      },
      json={
          "name": "Text to Image Generator",
          "description": "Generates images from text prompts",
          "categories": ["image-generation"],
          "definition": {
              "version": "v1",
              "input_schema": {
                  "type": "object",
                  "required": ["prompt"],
                  "properties": {
                      "prompt": {"type": "string"}
                  }
              },
              "steps": [
                  {
                      "step_id": "generate",
                      "type": "model",
                      "model": "flux-1-1-pro",
                      "params": {"prompt": "{{inputs.prompt}}"}
                  }
              ]
          }
      }
  )

  workflow = response.json()
  print(f"Created: {workflow['workflow_id']}")
  ```

  ```javascript JavaScript theme={"dark"}
  const response = await fetch(
    "https://workflows.eachlabs.run/api/v1/workflows",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_API_KEY",
      },
      body: JSON.stringify({
        name: "Text to Image Generator",
        description: "Generates images from text prompts",
        categories: ["image-generation"],
        definition: {
          version: "v1",
          input_schema: {
            type: "object",
            required: ["prompt"],
            properties: { prompt: { type: "string" } },
          },
          steps: [
            {
              step_id: "generate",
              type: "model",
              model: "flux-1-1-pro",
              params: { prompt: "{{inputs.prompt}}" },
            },
          ],
        },
      }),
    }
  );

  const workflow = await response.json();
  console.log(`Created: ${workflow.workflow_id}`);
  ```
</CodeGroup>

## Response

**Status: `201 Created`**

```json theme={"dark"}
{
  "workflow_id": "50741f40-8621-4d46-8a91-dff4d873be98",
  "slug": "text-to-image-generator",
  "name": "Text to Image Generator",
  "description": "Generates images from text prompts using AI models",
  "categories": ["image-generation"],
  "locked": false,
  "production": false,
  "latest_version_id": "v1",
  "status": "active",
  "trigger_count": 0,
  "created_at": "2025-12-01T10:00:00Z",
  "updated_at": "2025-12-01T10:00:00Z",
  "versions": [
    {
      "version_id": "v1",
      "slug": "text-to-image-generator",
      "locked": false,
      "production": false,
      "trigger_count": 0,
      "status": "active"
    }
  ]
}
```

## Error Responses

| Status | Body                                                     | Description             |
| ------ | -------------------------------------------------------- | ----------------------- |
| `400`  | `{"error": "name is required"}`                          | Missing required fields |
| `400`  | `{"error": "definition must include at least one step"}` | Empty steps array       |
| `401`  | `{"error": "Invalid or missing API key"}`                | Authentication failure  |