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

# API概要

> UTAGE APIの基本仕様とエンドポイント一覧

## ベースURL

```
https://api.utage-system.com/v1
```

## リクエスト形式

* HTTPメソッド: `GET`, `POST`, `PATCH`, `PUT`, `DELETE`
* Content-Type: `application/json`
* 文字コード: UTF-8
* 認証: `Authorization: Bearer {api_key}`

<Note>
  更新系エンドポイントの正規メソッドは `PATCH` です。`PUT` は後方互換のために利用できます。
</Note>

```bash リクエスト例 theme={null}
curl -X POST "https://api.utage-system.com/v1/funnels" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "新しいファネル"}'
```

## レスポンス形式

### 成功時

単一リソースの場合:

```json theme={null}
{
    "data": {
        "id": "fn_abc123",
        "name": "ファネル名"
    }
}
```

リスト取得の場合:

```json theme={null}
{
    "data": [
        {
            "id": "fn_abc123",
            "name": "ファネル1"
        },
        {
            "id": "fn_def456",
            "name": "ファネル2"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 20,
        "total": 42
    }
}
```

### エラー時

```json theme={null}
{
    "error": {
        "code": "validation_error",
        "message": "ファネル名は必須です"
    }
}
```

## ページネーション

一覧取得APIはページネーションに対応しています。クエリパラメータで制御できます。

| パラメータ      | 説明                | デフォルト |
| ---------- | ----------------- | ----- |
| `page`     | ページ番号             | 1     |
| `per_page` | 1ページあたりの件数（最大100） | 20    |

レスポンスの `meta` オブジェクトにページネーション情報が含まれます。

| フィールド          | 説明         |
| -------------- | ---------- |
| `current_page` | 現在のページ番号   |
| `per_page`     | 1ページあたりの件数 |
| `total`        | 全件数        |

## エンドポイント一覧

主要エンドポイントの抜粋です。全エンドポイントは左メニューの各カテゴリを参照してください。

### ファネル

| メソッド    | エンドポイント                | 説明                                     |
| ------- | ---------------------- | -------------------------------------- |
| `GET`   | `/funnels`             | [ファネル一覧](/api-reference/funnel/list)   |
| `POST`  | `/funnels`             | [ファネル作成](/api-reference/funnel/create) |
| `PATCH` | `/funnels/{funnel_id}` | [ファネル更新](/api-reference/funnel/update) |

### ステップ

| メソッド    | エンドポイント                                | 説明                                             |
| ------- | -------------------------------------- | ---------------------------------------------- |
| `GET`   | `/funnels/{funnel_id}/steps`           | [ステップ一覧](/api-reference/funnel/step-list)      |
| `POST`  | `/funnels/{funnel_id}/steps`           | [ステップ作成](/api-reference/funnel/step-create)    |
| `PATCH` | `/funnels/{funnel_id}/steps/{step_id}` | [ステップ更新](/api-reference/funnel/step-update)    |
| `PATCH` | `/funnels/{funnel_id}/steps/reorder`   | [ステップ並び替え](/api-reference/funnel/step-reorder) |

### ページ

| メソッド     | エンドポイント                                                | 説明                                         |
| -------- | ------------------------------------------------------ | ------------------------------------------ |
| `GET`    | `/funnels/{funnel_id}/steps/{step_id}/pages`           | [ページ一覧](/api-reference/funnel/page-list)   |
| `POST`   | `/funnels/{funnel_id}/steps/{step_id}/pages`           | [ページ作成](/api-reference/funnel/page-create) |
| `GET`    | `/funnels/{funnel_id}/steps/{step_id}/pages/{page_id}` | [ページ取得](/api-reference/funnel/page-get)    |
| `PATCH`  | `/funnels/{funnel_id}/steps/{step_id}/pages/{page_id}` | [ページ更新](/api-reference/funnel/page-update) |
| `DELETE` | `/funnels/{funnel_id}/steps/{step_id}/pages/{page_id}` | [ページ削除](/api-reference/funnel/page-delete) |

### 配信アカウント

| メソッド   | エンドポイント                            | 説明                                               |
| ------ | ---------------------------------- | ------------------------------------------------ |
| `GET`  | `/accounts`                        | [アカウント一覧](/api-reference/message/account-list)   |
| `POST` | `/accounts`                        | [アカウント作成](/api-reference/message/account-create) |
| `GET`  | `/accounts/{account_id}/scenarios` | [シナリオ一覧](/api-reference/message/scenario-list)   |
| `POST` | `/accounts/{account_id}/scenarios` | [シナリオ作成](/api-reference/message/scenario-create) |

### メディア

| メソッド  | エンドポイント                 | 説明                                                 |
| ----- | ----------------------- | -------------------------------------------------- |
| `GET` | `/media/videos`         | [動画一覧](/api-reference/media/video-list)            |
| `GET` | `/media/videos/folders` | [動画フォルダ一覧](/api-reference/media/video-folder-list) |
| `GET` | `/media/audios`         | [音声一覧](/api-reference/media/audio-list)            |
| `GET` | `/media/audios/folders` | [音声フォルダ一覧](/api-reference/media/audio-folder-list) |

### 要素タイプ

| メソッド  | エンドポイント                            | 説明                                                    |
| ----- | ---------------------------------- | ----------------------------------------------------- |
| `GET` | `/element-types/funnel`            | [要素タイプ一覧](/api-reference/funnel/element-types)        |
| `GET` | `/element-types/funnel/properties` | [要素プロパティ取得](/api-reference/funnel/element-properties) |

## HTTPステータスコード

| コード   | 説明                                              |
| ----- | ----------------------------------------------- |
| `200` | リクエスト成功                                         |
| `201` | リソース作成成功                                        |
| `400` | リクエスト不正（SMS設定不備、content\_type変更不可、不正なファイルタイプなど） |
| `401` | 認証エラー（APIキーが無効または未指定）                           |
| `403` | 権限エラー（アクセス権がないリソース）                             |
| `404` | リソースが見つからない                                     |
| `409` | 競合（送信中メッセージの更新・削除、重複登録など）                       |
| `422` | バリデーションエラー（リクエストパラメータの入力不備）                     |
| `429` | レート制限超過                                         |

## エラーコード

| コード                   | 説明                                |
| --------------------- | --------------------------------- |
| `unauthorized`        | APIキーが無効または未指定                    |
| `forbidden`           | リソースへのアクセス権がない                    |
| `not_found`           | 指定されたリソースが存在しない                   |
| `validation_error`    | リクエストパラメータのバリデーションエラー             |
| `conflict`            | リソースの状態が競合（送信中メッセージの更新・削除、重複登録など） |
| `rate_limit_exceeded` | レート制限を超過した                        |