> For the complete documentation index, see [llms.txt](https://help.genesis.autify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.genesis.autify.com/features-ja/integrations/api-guide.md).

# APIガイド

本記事では、Autify Genesis で利用できる API の種類・使い方・制限について説明します。

## API キーの管理

API キーの作成・確認・削除については、[APIキー管理](/features-ja/settings/organization-settings/api-key-management.md) を参照してください。

## ワークフローを API で実行する

外部アプリケーションやプログラムからワークフローを実行するには、**APIアクセス** を有効にする必要があります。

以下の手順で、設定の有効化とエンドポイントの確認を行います。

### 1. ワークフロー編集画面を開く

API で実行したいワークフローの編集画面を開きます。

### 2. トリガー設定メニューを表示する

画面上部の **その他のアクション** をクリックし、表示されたメニューから **トリガー** をクリックします。

<figure><img src="/files/CYgQJjWOpFtzJJ8HxsWU" alt="トリガー設定メニューのスクリーンショット"><figcaption><p>トリガー設定メニュー</p></figcaption></figure>

### 3. APIアクセスを有効にする

デフォルトでは APIアクセス は OFF に設定されています。

1. **APIアクセス** のスイッチを ON にします。
2. **並行実行ポリシー** で、同じワークフローの前回の API 実行がまだ待機中または実行中のときに、新しいリクエストをどう扱うかを選びます。

| 選択肢        | 内容                                                    |
| ---------- | ----------------------------------------------------- |
| 並行して実行     | 新しい実行を開始し、前回の実行もそのまま続けます                              |
| 前の実行をキャンセル | 同じワークフローの API 実行で、待機中または実行中の古い実行をキャンセルしてから新しい実行を開始します |

### 4. API エンドポイントを確認する

APIアクセス を ON にすると、専用の **APIエンドポイント** が表示されます。

<figure><img src="/files/l3caztz7vHeBzAjDaYhj" alt="API アクセスとエンドポイントのスクリーンショット"><figcaption><p>API アクセスとエンドポイント</p></figcaption></figure>

* エンドポイントの形式: `https://genesis.autify.com/api/workflows/{templateId}/trigger`

## REST API

API キーを使って、外部システムから Genesis のワークフローを実行したり、実行状況を確認したりできます。

### ワークフローのトリガー

**エンドポイント**

```http
POST /api/workflows/{templateId}/trigger
```

**リクエストヘッダー**

| ヘッダー           | 値                  | 説明 |
| -------------- | ------------------ | -- |
| `x-api-key`    | 発行した API キー        | 必須 |
| `Content-Type` | `application/json` | 推奨 |

**リクエストボディ**

ワークフローに定義されたコンテキスト変数に対応するキーと値のペアを JSON 形式で指定します。

```json
{
  "変数名1": "値1",
  "変数名2": "値2"
}
```

{% hint style="info" %}
ペイロードの値はすべて **文字列型** で指定してください。数値・配列・オブジェクトは使用できません。ワークフローに定義されていないキーを含めるとエラーになります。
{% endhint %}

{% hint style="info" %}
トリガー設定で **前の実行をキャンセル** を選んでいる場合、新しい API リクエストを送ると、同じワークフローの待機中または実行中の古い API 実行はキャンセルされてから新しい実行が始まります。
{% endhint %}

**レスポンス（成功時）**

```json
{
  "success": true,
  "executionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

返された `executionId` を使って、実行状況を確認できます。

**リクエスト例（curl）**

```bash
curl -X POST https://genesis.autify.com/api/workflows/{templateId}/trigger \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com"}'
```

### 実行状況の取得

**エンドポイント**

```http
GET /api/executions/{executionId}
```

**リクエストヘッダー**

| ヘッダー        | 値           | 説明 |
| ----------- | ----------- | -- |
| `x-api-key` | 発行した API キー | 必須 |

**リクエスト例（curl）**

```bash
curl -X GET https://genesis.autify.com/api/executions/{executionId} \
  -H "x-api-key: your-api-key"
```

**レスポンス例（成功時）**

```json
{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "running",
  "workflowName": "ワークフロー名",
  "blockCount": 5,
  "completedBlocks": 2,
  "createdAt": "2026-03-16T00:00:00.000Z",
  "updatedAt": "2026-03-16T00:00:05.000Z",
  "startedAt": "2026-03-16T00:00:01.000Z",
  "finishedAt": null,
  "cancelRequestedAt": null,
  "cancelReason": null,
  "error": null,
  "triggerType": "api",
  "triggerPayload": {
    "exampleField": "exampleValue"
  },
  "triggerMetadata": {
    "ip": "xxx.xxx.xxx.xxx",
    "userAgent": "curl/8.0.0",
    "apiKeyId": "ak_xxxxxxxxxxxx"
  },
  "state": {
    "workflowId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "executionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "running",
    "blocks": {
      "block-1": {
        "status": "completed",
        "startTime": "2026-03-16T00:00:01.000Z",
        "endTime": "2026-03-16T00:00:02.000Z",
        "inputs": {},
        "output": "..."
      }
    },
    "createdAt": "2026-03-16T00:00:00.000Z",
    "updatedAt": "2026-03-16T00:00:05.000Z"
  }
}
```

**実行ステータスの種類**

| ステータス            | 説明      |
| ---------------- | ------- |
| `pending`        | 実行待ち    |
| `running`        | 実行中     |
| `completed`      | 完了      |
| `failed`         | 失敗      |
| `cancelled`      | キャンセル済み |
| `skipped`        | 条件で未実行  |
| `review_pending` | レビュー待ち  |

## トラブルシューティング

### 認証エラー

| 状況                                                       | 原因                        | 対処方法                         |
| -------------------------------------------------------- | ------------------------- | ---------------------------- |
| `Missing API key`（401）                                   | `x-api-key` ヘッダーがない       | `x-api-key` ヘッダーを追加してください    |
| `Invalid API key`（401）                                   | API キーが無効または存在しない         | 正しい API キーを使用しているか確認してください   |
| `API key is not associated with an organization`（403）    | API キーに組織が紐付いていない         | 有効な API キーを再作成してください         |
| `Unauthorized`（403）                                      | API キーのユーザーが対象組織のメンバーでない  | 組織のメンバーが発行した API キーを使用してください |
| `API key does not have access to this organization`（403） | API キーの組織とワークフローの組織が一致しない | 同じ組織で発行した API キーを使用してください    |

### ペイロードエラー

| 状況                                                         | 原因                       | 対処方法                            |
| ---------------------------------------------------------- | ------------------------ | ------------------------------- |
| `Invalid JSON payload`（400）                                | リクエストボディが正しい JSON 形式でない  | JSON の構文を確認してください               |
| `Payload too large`（413）                                   | ペイロードが 10 MB を超えている      | ペイロードのサイズを 10 MB 以内に抑えてください     |
| `Invalid payload: expected object with string values`（500） | ペイロードの値が文字列以外（数値・配列など）   | すべての値を文字列型にしてください               |
| `Unexpected fields in payload`（500）                        | ワークフローに定義されていないキーが含まれている | ワークフローのコンテキスト変数に合わせてキーを修正してください |

### リソースエラー

| 状況                                                           | 原因                             | 対処方法                                      |
| ------------------------------------------------------------ | ------------------------------ | ----------------------------------------- |
| `Workflow template not found or API access not enabled`（404） | テンプレート ID が存在しないか、API トリガーが無効  | テンプレート ID を確認するか、ワークフローの API 設定を有効にしてください |
| `Invalid template ID`（400）                                   | テンプレート ID が UUID 形式でない         | 正しいテンプレート ID を使用してください                    |
| `Usage limit reached`（403）                                   | 組織のクレジット上限に達した                 | 管理者にクレジットの追加を依頼してください                     |
| `Workflow template must belong to a project`（400）            | テンプレートがプロジェクトに紐付いていない          | テンプレートを既存のプロジェクトに紐付けてください                 |
| `Project not found`（404）                                     | テンプレートに紐付くプロジェクトが存在しない         | プロジェクト設定を確認してください                         |
| `Execution not found`（404）                                   | 指定した `executionId` の実行履歴が存在しない | 有効な `executionId` を確認してください               |