> ## 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/ko/integrations/ad-units.md)로 유닛을 만들 때 넣을 앱 ID를 찾거나, 유닛의 `app`이 어느 앱인지 확인할 때 사용합니다.

> [!NOTE]
>
> 앱은 API로 만들거나 수정·삭제할 수 없습니다. 앱 등록과 관리는 콘솔에서 하세요. [앱 관리하기](https://docs.adrop.io/ko/ad-unit/create.md#앱-관리하기)를 참고하세요.

***

## 사전 준비

* `app:read` 권한(scope)이 있는 API 키가 필요합니다. 이 권한은 콘솔 **\[관리]** > **\[연동]** 메뉴에서 선택할 수 없습니다. 에이드랍에 요청하면 권한을 넣은 키를 발급해 드리며, [광고 유닛 API](https://docs.adrop.io/ko/integrations/ad-units.md)와 [광고 상품 API](https://docs.adrop.io/ko/integrations/ad-products.md) 권한도 같은 키에 함께 받을 수 있습니다.

> [!WARNING]
>
> API는 서버에서만 호출하세요. 앱이나 웹 페이지에 API 키를 넣지 마세요.

***

## 기본 정보

| 항목 | 값 |
| - | - |
| Base URL | `https://lake.adrop.io` |
| 인증 | `x-api-key` 헤더에 API 키를 넣습니다. 키가 속한 프로젝트의 앱만 조회할 수 있으며, 다른 프로젝트의 앱 ID는 `404`를 반환합니다. |
| ID 형식 | 영문자, 숫자, `_`, `-`로 된 64자 이하 문자열입니다. |
| 시각 | `createdAt`은 epoch 밀리초입니다. |

***

## 엔드포인트

경로는 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\~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"
}
```

***

## 앱 조회

앱 하나를 반환합니다.

### 요청

```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` 헤더의 시간(초)만큼 기다린 뒤 다시 보내세요. 요청을 하나씩 보내도 받을 수 있습니다. |
| `502` | - | 서버 내부 통신에 문제가 있습니다. |


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