---
title: "Create an Automation"
description: "Creates a draft, active, or paused Agent Y2 Automation."
canonical: https://y2.dev/docs/api/reference/automations/createAutomation/
---

Endpoint Reference[Automations](https://y2.dev/docs/api/reference/automations)

# Create an Automation

Creates a draft, active, or paused Agent Y2 Automation.

`POST https://api.y2.dev/api/v1/automations`

- Operation ID: `createAutomation`
- Required scopes: `automations:write`
- Contract: https://y2.dev/openapi.json

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | No | Client-generated retry key retained for 24 hours. Repeating the same key and canonical JSON body returns the original resource. Changing the body returns `409 IDEMPOTENCY_CONFLICT`. |

## Request body

`application/json`: `AutomationCreateRequest` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes |  |
| `instructions` | string | Yes |  |
| `projectId` | string or null | No |  |
| `trigger` | `AutomationTrigger` | Yes |  |
| `notificationPolicy` | `all_runs`, `failures_only`, `none` | Yes |  |
| `status` | `draft`, `active`, `paused` | No |  |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 201 | Automation created | `AutomationMutationResponse` |
| 400 | Invalid request parameters |  |
| 401 | Missing or invalid API key |  |
| 403 | Insufficient permissions or access denied |  |
| 409 | Resource conflict (e.g., webhook in use) |  |
| 429 | Rate limit exceeded (per-key or per-account aggregate) |  |
| 500 | Internal server error |  |

### 201 response fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | `Automation` |  |
| `data.id` | string |  |
| `data.type` | string |  |
| `data.name` | string |  |
| `data.instructions` | string |  |
| `data.operation` | string |  |
| `data.projectId` | string or null |  |
| `data.trigger` | `AutomationTrigger` |  |
| `data.notificationPolicy` | `all_runs`, `failures_only`, `none` |  |
| `data.overlapPolicy` | string |  |
| `data.status` | `AutomationStatus` |  |
| `data.definitionRevision` | integer |  |
| `data.schedule` | null or `AutomationSchedule` |  |
| `data.lastRun` | null or `AutomationRun` |  |
| `data.createdAt` | string (date-time) |  |
| `data.updatedAt` | string (date-time) |  |
| `data.links` | object |  |
| `meta` | object |  |
| `meta.message` | string |  |