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

# アプリAPI

> APIキーを使って、サーバーからプロジェクトに登録されたアプリの一覧とアプリの情報を取得する方法をご案内します。

アプリAPIを使うと、プロジェクトに登録されたアプリを取得できます。[広告ユニットAPI](https://docs.adrop.io/ja/integrations/ad-units.md)でユニットを作成するときに指定するアプリIDを調べたり、ユニットの`app`がどのアプリかを確認したりするときに使います。

> [!NOTE]
>
> アプリはAPIで作成・更新・削除できません。アプリの登録と管理はコンソールで行ってください。[アプリの管理](https://docs.adrop.io/ja/ad-unit/create.md#アプリの管理)を参照してください。

***

## 事前準備

* `app:read`スコープを持つAPIキーが必要です。このスコープは、コンソールの **\[設定]** > **\[連携]** メニューでは選択できません。Adropにご依頼いただければ、スコープを含むキーを発行します。[広告ユニットAPI](https://docs.adrop.io/ja/integrations/ad-units.md)と[広告商品API](https://docs.adrop.io/ja/integrations/ad-products.md)のスコープも、同じキーにあわせて含めることができます。

> [!WARNING]
>
> APIはサーバーからのみ呼び出してください。APIキーをアプリやウェブページに含めないでください。

***

## 基本情報

| 項目 | 値 |
| - | - |
| Base URL | `https://lake.adrop.io` |
| 認証 | `x-api-key`ヘッダーにAPIキーを指定します。キーが属するプロジェクトのアプリのみ取得できます。ほかのプロジェクトのアプリIDは`404`を返します。 |
| IDの形式 | 英数字、`_`、`-`からなる64文字以内の文字列です。 |
| 時刻 | `createdAt`はエポックミリ秒です。 |

***

## エンドポイント

パスはBase URLを基準とします。

| メソッド | パス | スコープ | 説明 |
| - | - | - | - |
| `GET` | `/apps` | `app:read` | [アプリ一覧の取得](#アプリ一覧の取得) |
| `GET` | `/apps/{appId}` | `app:read` | [アプリの取得](#アプリの取得) |

***

## アプリオブジェクト

| フィールド | 型 | 説明 |
| - | - | - |
| `_id` | string | アプリID |
| `title` | string | アプリ名 |
| `platform` | string | アプリのプラットフォーム：`android`、`ios`、`web`、`api`、`flutter`、`react`、`unity` |
| `createdAt` | number | アプリを登録した時刻 |

SDKの初期化に使うアプリキーなどの設定情報は、レスポンスに含まれません。

***

## アプリ一覧の取得

プロジェクトのアプリをページ単位で返します。並び順はおおむね登録した順ですが、古いアプリは順序が異なる場合があります。順序に頼らず、`next`で続きを読み込んでください。

### リクエスト

```http theme={null}
GET /apps
```

`app:read`スコープが必要です。

### クエリパラメーター

| パラメーター | 型 | 必須 | デフォルト値 | 説明 |
| - | - | :-: | - | - |
| `limit` | number | - | `20` | 1回で受け取るアプリの数（1〜120） |
| `next` | string | - | - | 次のページのカーソル。前のレスポンスの`next`をそのまま入れます。最初のページでは省略します。 |

### リクエスト例

```bash theme={null}
curl "https://lake.adrop.io/apps?limit=20" \
  -H "x-api-key: YOUR_API_KEY"
```

### レスポンス例

`200`で、`items`（アプリの一覧）と`next`（次のページのカーソル）を返します。`next`がなければ最後のページです。

```json theme={null}
{
  "items": [
    {
      "_id": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
      "title": "My App",
      "platform": "android",
      "createdAt": 1790820300000
    }
  ],
  "next": "01JAZ3K9Q8W5T2M4N6P7R8S9TV"
}
```

***

## アプリの取得

1つのアプリを返します。

### リクエスト

```http theme={null}
GET /apps/{appId}
```

`app:read`スコープが必要です。

### リクエスト例

```bash theme={null}
curl "https://lake.adrop.io/apps/01JAZ3K9Q8W5T2M4N6P7R8S9TV" \
  -H "x-api-key: YOUR_API_KEY"
```

### レスポンス

`200`で[アプリオブジェクト](#アプリオブジェクト)を返します。

### エラー

* `404 PROJECT_APP_NOT_FOUND`: アプリが存在しないか、ほかのプロジェクトのアプリです。

***

## エラー処理

エラーレスポンスには`statusCode`が含まれ、下の表で`errorCode`の欄が`-`ではないエラーには`errorCode`も含まれます。処理は`errorCode`で分け、`errorCode`がない場合は`statusCode`で分けてください。リクエスト形式のエラー（`VALIDATION_FAILED`）では、誤っている箇所を`detail.errors[]`の`path`で知らせます。

| ステータス | `errorCode` | 原因 |
| - | - | - |
| `400` | `VALIDATION_FAILED` | アプリIDや`next`の形式が誤っているか、`limit`が範囲外であるか、不明なクエリパラメーターを送りました。 |
| `401` | - | APIキーがない、誤っている、または廃棄されています。 |
| `403` | - | `app:read`スコープがありません。 |
| `404` | `PROJECT_APP_NOT_FOUND` | アプリが存在しないか、ほかのプロジェクトのアプリです。 |
| `429` | `TOO_MANY_CONCURRENT_REQUESTS` | サーバーが混雑しています。`Retry-After`ヘッダーの秒数だけ待ってから再送信してください。リクエストを1件ずつ送っても返されることがあります。 |
| `502` | - | サーバー内部の通信に問題があります。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.