# オートメーション API

オートメーションとは、ステップで構成されるワークフローです。開始のトリガー（1つ以上）、アクション、条件、遅延、AIステップなどがグラフ状に接続されています。これは、[オートメーション](../automations/automations.md)ページで表示・編集するものと同じです。このガイドでは、APIを通じてこれらを読み取り、構築する方法を説明します。

- **ベースURL**: `https://api.dmchamp.com/v1`
- **認証**: APIキー（[認証](authentication.md)を参照）
- **フィールドとボディ**: すべてのパラメータおよびレスポンスフィールドは[APIリファレンス](reference.md#tag/automations)に記載されています
- **エラー**: 下記の[エラーとページネーション](errors-and-pagination.md)および[エラー](#errors)を参照してください

> **代理店:** このページのすべてのエンドポイントはクエリパラメータとして `sub_account_id` を受け入れるため、代理店キーを使用してクライアントのオートメーションを読み取り、構築できます。クライアントアカウントではない `sub_account_id` を指定すると `404` が返されます。[代理店向けAPI](../agency/api-for-agencies.md)を参照してください。

---

## 仕組み：まずはドラフトから

このAPIは、誤って実行が開始されることがないように設計されています。

1. **カタログを読み取る。** `GET /automations/steps` には、使用可能なすべてのトリガー、アクション、ステップの種類と、グラフを記述するための文法（`graph_rules`）が記載されています。
2. **ドラフトを作成する。** `POST /automations` は、オートメーションを**オフの状態**で保存します。まだ何も実行されません。
3. **確認する。** 読み戻してビルダーで開き（レスポンスで `open_path` が得られます）、アカウント所有者がその動作と対象を把握していることを確認します。
4. **オンにする。** `POST /automations/{automationId}/enable` は専用の呼び出しです。このステップを実行することで、メッセージの送信、レコードの変更、AIエージェントへのツール提供など、実際の処理が行われます。

編集を行っても、オートメーションのオン/オフ状態は変わりません。つまり、**オン**になっているオートメーションを編集すると、その変更は直ちにライブ環境のオートメーションに反映されます。実行中のオートメーションを安全に変更するには、無効化し、編集・確認を行った後、再度有効化してください。

送信するすべてのグラフは、ビルダーキャンバスが適用するものと同じチェックを受けます。開くことや実行することができないグラフは、修正すべき箇所を正確にリストアップした `400` を返して拒否されます。

### アクセス権

- アカウントには「オートメーション」機能が必要です。これがない場合、このページのすべての呼び出しは `403` を返します。
- チームメンバーのアクセス権は、[チーム管理](../settings/team-management.md)における「**オートメーション**」エリアの権限に従います。読み取り（一覧、取得、ステップ、実行履歴、フォルダ）には「**表示**」権限が、変更を伴うすべての操作には「**編集**」権限が必要です。
- オートメーションの作成や編集が許可されていないプランのクライアントアカウントでは、アプリ内のビルダーと同様に、書き込み呼び出しは `403` を返します。

---

## エンドポイント

| タスク | メソッド + パス | エクスプローラー |
|---|---|---|
| オートメーションの一覧表示 | `GET /automations` | [APIリファレンスで開く](reference.md#tag/automations/GET/automations) |
| オートメーションをグラフ付きで取得 | `GET /automations/{automationId}` | [APIリファレンスで開く](reference.md#tag/automations/GET/automations/{automationId}) |
| ステップカタログの読み取り | `GET /automations/steps` | [APIリファレンスで開く](reference.md#tag/automations/GET/automations/steps) |
| オートメーションの作成（ドラフト） | `POST /automations` | [APIリファレンスで開く](reference.md#tag/automations/POST/automations) |
| オートメーションの更新 | `PUT /automations/{automationId}` | [APIリファレンスで開く](reference.md#tag/automations/PUT/automations/{automationId}) |
| 有効化 | `POST /automations/{automationId}/enable` | [APIリファレンスで開く](reference.md#tag/automations/POST/automations/{automationId}/enable) |
| 無効化 | `POST /automations/{automationId}/disable` | [APIリファレンスで開く](reference.md#tag/automations/POST/automations/{automationId}/disable) |
| 実行履歴の読み取り | `GET /automations/{automationId}/runs` | [APIリファレンスで開く](reference.md#tag/automations/GET/automations/{automationId}/runs) |
| フォルダーの一覧表示 | `GET /automations/folders` | [APIリファレンスで開く](reference.md#tag/automations/GET/automations/folders) |
| フォルダーの作成 | `POST /automations/folders` | [APIリファレンスで開く](reference.md#tag/automations/POST/automations/folders) |
| フォルダーの名前変更 | `PUT /automations/folders/{folderId}` | [APIリファレンスで開く](reference.md#tag/automations/PUT/automations/folders/{folderId}) |
| フォルダーの削除 | `DELETE /automations/folders/{folderId}` | [APIリファレンスで開く](reference.md#tag/automations/DELETE/automations/folders/{folderId}) |
| オートメーションをフォルダーに移動 | `PUT /automations/{automationId}/folder` | [APIリファレンスで開く](reference.md#tag/automations/PUT/automations/{automationId}/folder) |

---

## オートメーションの読み取り

`GET /automations` は（ステップを含まない）概要を、最近変更された順に返します。`folder_id=none` はフォルダーに属していないオートメーションを一覧表示します。`GET /automations/{automationId}` は完全な `graph` を追加します。これには各ステップ（`nodes[]`）とその `kind`、`label`、`alias`、`action`、`params`、`config`、および接続（`edges[]`）が含まれ、接続には `from`、`to`、そして条件分岐などの後には `branch` が含まれます。

```bash
curl "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f?apiKey=YOUR_API_KEY"
```

**知っておくべきこと**

- **`alias` は、後続のステップがステップの出力を `${nodes.<alias>.<field>}` として読み取る方法です。** 出力を持たないステップは、そのIDで参照されます。
- `params` は古いリーダーとの互換性のために保持されています。`config` は同じ値に加え、さらに多くの情報（条件のルール、AIステップのプロンプト、遅延時間、アクションのslugとパラメータなど）を保持します。
- **シークレットは非表示になります。** 認証情報のように見える値（Webhookシークレット、トークン、APIキー、パスワード、ヘッダー値など）は `"[redacted]"` として返されます。`"[redacted]"` を変更せずに送り返すと、保存されている値が維持されます。
- **長いテキストは短縮されます。** 約4,000文字を超える単一のテキストは切り詰められ、末尾が省略記号になります。そのステップを送り返す場合は、先に完全なテキストを戻してください。
- オートメーションサービスに到達できない場合は `503` が返されます。空のリストが返されることはありません。空のリストは、オートメーションが存在しないことを意味します。

### ステップカタログ

`GET /automations/steps` は、オートメーションの構築に使用できるすべての要素を返します。8つの `node_kinds`、設定 `fields` と `output_keys` を持つすべてのトリガー、パラメータを持つ組み込みの `actions`、`api_actions`（アクションステップが呼び出せるこのAPIの操作）、`graph_rules` 文法、および `counts` です。これはビルダーが **提供するもの** であり、アカウントが構築したものではありません。トリガーやアクションが存在しないと結論付ける前に、これを確認してください。

- `q` がない場合、数百あるAPIアクションは `api_actions_by_tag` 内のエリアごとにグループ化されたラベルとして返され、フラットリストは空になります。
- `q`（大文字小文字を区別しない単語）を指定すると、`api_actions` は一致した項目のフラットリストとなり、最大60件まで表示されます（`api_actions_truncated` でその旨が示されます）。接続されたサードパーティアプリのアクションも検索され、`app_actions` に返されます。例えば `q=hubspot` のようにアプリ名で検索してください。それぞれのアクションには、アカウントがそのアプリを `connected` しているかどうかが示され、`connected_apps` に接続済みのアプリが一覧表示されます。`app_actions_unavailable` は、今回アプリのアクションを検索できなかった場合に `true` となります。他のリストは完全なままです。

---

## 作成と編集

### ドラフトの作成

```bash
curl -X POST "https://api.dmchamp.com/v1/automations?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Price question auto-reply",
    "description": "Replies with the price list when someone asks about prices.",
    "graph": {
      "nodes": [
        { "id": "trigger_1", "type": "trigger", "label": "Incoming message",
          "data": { "trigger": { "kind": "incoming_message", "message_filter_contains": "price" } } },
        { "id": "send_prices", "type": "action", "label": "Send message",
          "data": { "action": { "provider": "native", "slug": "SEND_MESSAGE",
            "params": { "contact_id": "${trigger.contact.id}", "body": "Hi ${trigger.contact.first_name}, here is our price list: https://example.com/prices" } } } }
      ],
      "edges": [{ "source": "trigger_1", "target": "send_prices" }]
    }
  }'
```

```json
{ "success": true, "automation": { "id": "8d2c7f1e-…", "enabled": false, "…": "…" }, "draft": true, "open_path": "/automations/8d2c7f1e-…", "warnings": [] }
```

`draft: true` と `enabled: false` は正常な動作であり、失敗ではありません。新しいオートメーションは、有効化するまでは常にドラフト状態です。`warnings` は、ビルダーが完了できなかった内容を短いラベル（例: `agent_function:not_linked`）として一覧表示します。

**グラフの記述。** カタログからの `graph_rules` が完全な文法です。要約すると以下の通りです。

- 各ノードには `id`（グラフ内で一意）、`type`（8つの[ステップの種類](#step-kinds)のいずれか）、オプションの `label`、およびそのタイプ（`data.trigger`、`data.action`、`data.condition`、`data.delay`、`data.ai`、`data.loop`、`data.transform`、`data.respond`）にちなんで名付けられたキーの下にある `data` 内の設定が含まれます。
- オートメーションには少なくとも1つのトリガーが必要です。ライブ文法では最大10個まで許可されており、いずれかが発火するとオートメーションが開始されます。
- 他のすべてのステップはトリガーから到達可能である必要があり、前のステップに戻るような接続は許可されません。
- 条件分岐から出るエッジには `sourceHandle` `true` または `false` が含まれます。ループには `body` または `done` が、返信待ちの遅延には `replied` または `timed_out` が含まれます。その他のエッジには何も含まれません。
- アクションのslugとパラメータはカタログから取得します。エージェント、タグ、リスト、ステージなどの **IDを推測しないでください**。最初にAPIで検索するか、ビルダーでユーザーが選択できるようにフィールドを `""` のままにしてください。
- 位置情報はオプションです。指定がないステップは自動的に配置されます。
- 前のステップからの値は `${trigger.<field>}` および `${nodes.<step>.<field>}` として記述されます。[前のステップの戻り値を使用する](../automations/automations.md#using-what-an-earlier-step-returned)および[式](../automations/automations.md#expressions)を参照してください。
- グラフは2つの表記法で受け入れられます。ビルダー独自の表記法（上記）と、読み取り時に返される表記法（`kind`、`config`、`from`、`to`、`branch`）です。そのため、オートメーションを読み取り、ステップを変更して送り返すことができます。
- **作成操作を盲目的に繰り返すのは安全ではありません。** リクエストがタイムアウトした場合は、再度送信する前にオートメーションの一覧を取得してください。そうしないと、ドラフトが2つ作成される可能性があります。

### 更新

`PUT /automations/{automationId}` は `name`、`description`、および/または `graph` を変更します（少なくとも1つ、または `400`）。`graph` はグラフの**全体**を置き換えるため、常に保存されている内容に基づいて作業してください。つまり、読み取り、必要な箇所を変更し、グラフ全体を送信し直します。

```bash
curl -X PUT "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Price question auto-reply (EN)" }'
```

- **各ステップの `alias` は、取得した通りに保持してください。** 変更したり削除したりすると、そのステップへのすべての参照が空になります。[ステップの名前付け](../automations/automations.md#naming-your-steps) を参照してください。
- **`"[redacted]"` の値はそのままにし**、**省略されたテキストを復元してください**（末尾が省略記号のテキストは、読み取り時に切り詰められています）。
- 自動化がオンかどうかは、ここでは変更されません。オンの場合、編集内容は保存されるとすぐに反映されます。オンの状態で、自分自身をトリガーするような変更を行うと拒否されます。その場合は、先に無効化してください。

### 有効化と無効化

`POST /automations/{automationId}/enable` は自動化をオンにし、以降はトリガーに基づいて実行されるようにします。アカウントの所有者が自動化の動作と対象を確認し、同意した場合にのみ呼び出してください。ビルダーは、実行できないグラフ（トリガーがない、ループしている、自分自身をトリガーするステップがあるなど）のオンへの切り替えを拒否し、その理由を示す `400` を返します。

```bash
curl -X POST "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/enable?apiKey=YOUR_API_KEY"
```

`POST /automations/{automationId}/disable` は自動化を一時停止します。実行中の処理は完了しますが、新しい実行は開始されません。無効化は常に許可されます。どちらの呼び出しもボディを必要としません。

---

## 実行履歴

`GET /automations/{automationId}/runs` は、1つの自動化の実行履歴を新しい順に返します（`limit` は1〜50、デフォルトは10）。各実行の開始時刻と終了時刻、トリガーとなったもの、成功したかどうか、失敗した場合はそのエラー内容が含まれます。自動化を読み取ると、それが**何をするか**がわかります。実行履歴は、それが**何をしたか**を示します。また、一度も実行されていない自動化と、実行されるたびに失敗する自動化を区別する唯一の方法です。

```bash
curl "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/runs?apiKey=YOUR_API_KEY&limit=20"
```

- `mode` は実際の実行の場合は `live`、エディターからの **安全な実行 (Safe run)** の場合は `safe` です。安全な実行では何も送信されないため、自動化が実際の運用で機能することの証明にはなりません。
- 空の `runs` リストは回答であり、欠落ではありません。その場合、レスポンスには `note` が含まれます。これは、トリガーが一度も発生していないか、自動化がオフになっていることを意味します。

---

## フォルダー

フォルダーはリスト内でオートメーションをグループ化するだけであり、オートメーションの動作や有効・無効の状態を変更することはありません。[フォルダーによるオートメーションの整理](../automations/automations.md#organizing-automations-in-folders)を参照してください。

```bash
curl -X PUT "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/folder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "folder_id": "f1a2b3c4-5d6e-7f80-91a2-b3c4d5e6f708" }'
```

- フォルダーを一覧表示すると、フォルダーに属していない自動化の数である `unfiled_count` も返されます。
- フォルダー名は必須で、最大100文字まで、アカウント内で一意である必要があります（`409`、`code: "folder_name_taken"`）。自動化の作成時に `folder_id` を渡すことで、フォルダーに分類することもできます。
- 名前を変更しても、自動化の場所は変わりません。
- **フォルダーを削除しても、フォルダーのみが削除されます。** その中の自動化はフォルダーなしの状態になり、これまで通り実行され続けます。レスポンスには移動した数が示されます（`moved_to_no_folder`）。
- 移動時には `folder_id` が必須です。`null` を送信すると、自動化をフォルダーから外すことができます。

---

## カタログ

### ステップの種類

| 種類 | 動作 |
|---|---|
| `trigger` | 何かが発生したときにオートメーションを開始します。 |
| `action` | 1つのステップを実行します（組み込みアクション、APIアクション、接続済みアプリのアクション、HTTPリクエスト、またはメール）。 |
| `condition` | ルールに基づいてフローを `true` と `false` の分岐に分割します。 |
| `transform` | ステップ間でデータを整形するための短いコードを実行します。 |
| `ai` | 作成したプロンプトを使用してAIに質問します。テキストの返信、フィールドの分離、または複数の分岐のいずれかを選択させることができます。 |
| `delay` | 指定した時間待機するか、連絡先からの返信を（タイムアウト付きで）待ちます。 |
| `loop` | リスト内の各アイテムに対して、内部のステップを繰り返します。 |
| `respond` | 実行を開始したWebhook呼び出しまたはAIエージェント関数呼び出しに対してレスポンスを返します。 |

### トリガー

これらはカタログに現在リストされている40個のトリガーであり、ビルダーでのグループ分けに従って分類されています。**設定**列には、トリガーがいつ起動するかを絞り込むためのトリガー独自の設定キー (`fields`) が含まれています。すべてのトリガーは `respect_quiet_hours`、`run_hours`、`reentry`、および `stop_on_response` も受け取ります。[オートメーション設定](../automations/automations.md#automation-settings) を参照してください。

**メッセージング**

| トリガー (`kind`) | 起動条件 | 設定 |
|---|---|---|
| 受信メッセージ (`incoming_message`) | 連絡先が任意のチャネルでメッセージを送信したとき。 | `campaign` (AIエージェントを1つに限定)、`channel`、`message_filter_contains` (キーワード)、`message_filter_regex` (パターン) |
| 不在着信 (`missed_call`) | WhatsApp Web番号または自身のSMS番号への着信に応答がなかったとき。 | `to_number` |
| メッセージ配信済み (`message_delivered`) | 送信したメッセージがチャネルによって配信済みと確認されたとき。 | `channel`、`agent` |
| メッセージ失敗 (`message_failed`) | 送信したメッセージがエラーにより配信できなかったとき。 | `channel`、`agent` |
| メッセージ送信済み (`message_sent`) | AI、あなた、ブロードキャスト、フォローアップなど、アカウントからメッセージが送信されたとき。フィルターを設定しないとすべてに適用されます。 | `channel`、`sent_by` |
| フォローアップ送信済み (`follow_up_sent`) | 自動フォローアップが送信されたとき。 | なし |
| フォローアップスキップ (`follow_up_skipped`) | 送信条件を満たさなかったため、フォローアップが保留されたとき。 | なし |
| フォローアップ完了 (`follow_up_exhausted`) | 連絡先がシーケンス内の最後のフォローアップを受け取り、キューに何も残っていないとき。 | なし |
| 会話終了 (`conversation_closed`) | チャットが終了したとき（終了理由と要約を含む）。 | `channel`、`agent` |
| ブロードキャスト完了 (`broadcast_completed`) | ブロードキャストの送信が完了したとき（送信数と失敗数を含む）。 | なし |
| リード返信分類 (`outreach_reply_labelled`) | コールドメールのリードからの返信が分類されたとき（例: 興味あり）。 | `label` |
| Skoolコメント受信 (`skool_comment_received`) | メンバーが、コメントルールで監視しているSkool投稿にコメントしたとき。 | なし |

**連絡先**

| トリガー (`kind`) | 起動条件 | 設定 |
|---|---|---|
| 新規連絡先 (`contact_created`) | 任意のチャネルで新しい人物から初めて連絡があったとき、またはインポート、API、手動作成された連絡先の場合。 | なし |
| 連絡先更新 (`contact_updated`) | 連絡先フィールドが変更されたとき。 | `field` |
| ここに追加した連絡先 (`contact_added`) | [連絡先] ページからこのオートメーションに手動で追加した連絡先のみ。連絡先ごとに1回実行されます。 | なし |
| タグ付与 (`tag_applied`) | AIエージェント、担当者、オートメーション、またはインポートによってタグが追加されたとき。 | `tag_name`、`channel`、`applied_by` |
| タグ削除 (`tag_removed`) | 連絡先からタグが削除されたとき。 | `tag_name`、`channel` |
| Skoolメンバー参加 (`skool_member_joined`) | 管理または運営するSkoolコミュニティに誰かが参加したとき（プロフィール、回答、適合スコアを含む）。 | `group_id`、`create_contact` |
| Skoolメンバー適格 (`skool_member_qualified`) | 新しいSkoolメンバーの回答スコアがしきい値以上になったとき。 | `min_score` |

**取引**

| トリガー (`kind`) | 起動条件 | 設定 |
|---|---|---|
| 取引作成 (`deal_created`) | パイプラインに新しい取引が追加されたとき。 | `pipeline_id`、`stage_id` |
| 取引ステージ変更 (`deal_stage_changed`) | 取引が別のステージに移動したとき（移動元と移動先のステージ名を含む）。 | `pipeline_id`、`to_stage_id`、`from_stage_id` |
| 取引更新 (`deal_updated`) | 取引フィールドが変更されたとき。 | `field` |

**予約**

| トリガー (`kind`) | 起動条件 | 設定 |
|---|---|---|
| 予約完了 (`appointment_booked`) | 新しい予約が確定したとき。 | なし |
| 予約キャンセル (`appointment_cancelled`) | 予約済みの予定がキャンセルされたとき。 | なし |
| 予約変更 (`appointment_rescheduled`) | 予約済みの予定が別の時間に変更されたとき（旧時間と新時間を含む）。 | `event_id` |
| 予約前 (`appointment_upcoming`) | 確定した各予約の指定時間前（リマインダー用）。オートメーションごとに最大5つのリマインダー。 | `offsets_minutes` |

**タスク**

| トリガー (`kind`) | 起動条件 | 設定 |
|---|---|---|
| タスク作成 (`task_created`) | タスクが作成されたとき。 | `task_type` |
| タスク完了 (`task_completed`) | タスクが完了ステージに移動したとき。 | なし |

**アカウント**

| トリガー (`kind`) | 起動条件 | 設定 |
|---|---|---|
| クレジット残高不足 (`low_credit_balance`) | クレジット残高がアラートしきい値を下回ったとき。 | なし |
| チャネル接続 (`channel_connected`) | チャネルの接続が完了したとき。 | `channel` |
| チャネル切断 (`channel_disconnected`) | チャネルが切断されたとき（ログアウト、リンク解除、遮断）。WhatsApp Web番号が自動再接続する場合、30分経過しても復旧しない場合のみカウントされます。 | `channel` |

**エージェンシー**

| トリガー (`kind`) | 起動条件 | 設定 |
|---|---|---|
| サブアカウント作成 (`sub_account_created`) | ダッシュボード、API、またはサインアップページから新しいクライアントアカウントが作成されたとき。 | なし |
| サブアカウントアクティビティ (`sub_account_event`) | クライアントアカウントで何らかのイベントが発生したとき（クレジット不足、チャネル接続、プラン変更など）。 | `event`、`threshold` |

**全般およびアプリ**

| トリガー (`kind`) | 起動条件 | 設定 |
|---|---|---|
| スケジュール (`schedule`) | cronスケジュールに従う。 | `cron`, `timezone` |
| Webhook (`webhook`) | 外部システムがオートメーションのWebhookアドレスを呼び出す。 | `webhook_secret` |
| AIエージェント機能 (`agent_function`) | 会話中にAIエージェントがこのオートメーションを関数として呼び出す。 | `function_name`, `function_description`, `parameters`, `agent_ids`, `campaign_ids` |
| 新着フィードアイテム (`rss`) | RSSまたはAtomフィードに新しいアイテムが表示される。 | `feed_url` |
| メール受信 (`email_received`) | 接続済みのメールボックスにメールが届く。 | `from_contains`, `subject_contains` |
| アプリイベント (`app_event`) | 接続済みアプリで何らかのイベント（取引ステージの変更、支払いの受領、フォームの送信など）が発生する。 | `toolkit`, `trigger_slug`, `connected_account_id`, `config` |
| 手動実行 (`manual`) | 手動で開始された場合のみ。 | なし |

1つのオートメーションには、`webhook`、`app_event`、`agent_function`、`rss`、`schedule`、`email_received`、`appointment_upcoming`、`contact_added`の各トリガーを最大1つずつ設定できます。レコード作成時に起動するトリガーは、同じレコードを作成するアクションと組み合わせることはできません。オートメーションが無限ループに陥る可能性があるためです。

各トリガーが後続のステップに渡す内容（`output_keys`）や、パラメータを含むアクションの全リストについては、`GET /automations/steps`を参照してください。[オートメーションガイド](../automations/automations.md#triggers)では、ビルダーの用語を用いて各トリガーを解説しています。

---

## エラー

すべてのエラーは通常の形式 `{ "success": false, "error_code": <status>, "error": "..." }` をとります。拒否されたグラフには `code` と `errors` が追加されます。`errors` はすべての問題を1文ずつの修正可能な形式でリストし、`error` はその最初のエラーです。リストされた内容を正確に修正し、グラフ全体を再度送信してください。`code` は `invalid_graph`、`automation_graph_has_a_cycle`、`self_triggering_automation`、`no_trigger`、またはビルダーからのその他のコードのいずれかです。

| ステータス | 時期 |
|---|---|
| `400` | グラフが拒否されました。必須フィールドが不足している（作成時に `name` または `graph`、移動時に `folder_id`）、更新で変更内容が送信されなかった、IDが無効、またはフォルダー名が不足している、空である、長すぎる（`code: "invalid_name"`）などの理由です。 |
| `403` | アカウントに自動化機能がない、クライアントアカウントのプランに自動化の作成・編集が含まれていない（書き込みのみ）、またはチームメンバーの **自動化** へのアクセス権限が低すぎます。 |
| `404` | このアカウントにそのIDの自動化が存在しない、そのIDのフォルダーが存在しない（`code: "folder_not_found"`）、またはクライアントアカウントではない `sub_account_id` が指定されました。 |
| `409` | その名前のフォルダーが既に存在します（`code: "folder_name_taken"`）。 |
| `413` | 自動化がビルダーの許容する1MBを超えています。大きなコードやデータはステップの外に出してください。 |
| `422` | ビルダーが他の理由でリクエストを拒否しました。`GET /automations/steps` と照らし合わせてグラフを確認してください。同じリクエストを再送しても解決しません。 |
| `503` | 自動化サービスに接続できませんでした。しばらくしてから再試行してください。作成時の場合は、2つ目のドラフトを作成しないように、まず自動化の一覧を取得してください。 |

::: master-only
## MCP経由でのこれらのエンドポイントの使用

このページのすべてのエンドポイントは、[MCP経由で接続](../integrations/connect-ai-clients.md)するAIアシスタントのツールとしても利用可能です。ルールは同じで、新しいオートメーションは有効化されるまでドラフト状態であり、実行中のオートメーションへの編集は即座に反映されます。

| ツール | エンドポイント |
|---|---|
| `list_automations` | `GET /automations` |
| `get_automation` | `GET /automations/{automationId}` |
| `list_automation_steps` | `GET /automations/steps` |
| `create_automation` | `POST /automations` |
| `update_automation` | `PUT /automations/{automationId}` |
| `enable_automation` | `POST /automations/{automationId}/enable` |
| `disable_automation` | `POST /automations/{automationId}/disable` |
| `list_automation_runs` | `GET /automations/{automationId}/runs` |
| `list_automation_folders` | `GET /automations/folders` |
| `create_automation_folder` | `POST /automations/folders` |
| `rename_automation_folder` | `PUT /automations/folders/{folderId}` |
| `delete_automation_folder` | `DELETE /automations/folders/{folderId}` |
| `move_automation_to_folder` | `PUT /automations/{automationId}/folder` |
:::

---

## 次のステップ

- [オートメーション](../automations/automations.md): ビルダーにおけるトリガー、ステップ、変数、実行履歴の仕組み。
- [エージェンシー向けAPI](../agency/api-for-agencies.md): `sub_account_id` を使用してクライアントアカウント上にオートメーションを構築する方法。
- [APIリファレンス](reference.md): インタラクティブなエンドポイントエクスプローラーの全機能。