> ## 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.

# App API

> Learn how to list the apps registered in your project and get app details from your server with an API key.

The App API lets you look up the apps registered in your project. Use it to find the app ID to send when you create a unit with the [Ad Unit API](https://docs.adrop.io/integrations/ad-units.md), or to check which app a unit's `app` refers to.

> [!NOTE]
>
> You can't create, update, or delete apps with the API. Register and manage apps in the console. See [Managing Apps](https://docs.adrop.io/ad-unit/create.md#managing-apps).

***

## Prerequisites

* You need an API key with the `app:read` scope. You can't select this scope in **\[Settings]** > **\[Integrations]** in the console. Ask Adrop, and we'll issue you a key with the scope. You can get the [Ad Unit API](https://docs.adrop.io/integrations/ad-units.md) and [Ad Product API](https://docs.adrop.io/integrations/ad-products.md) scopes on the same key.

> [!WARNING]
>
> Call the API from your server only. Don't put API keys in apps or web pages.

***

## Basics

| Item | Value |
| - | - |
| Base URL | `https://lake.adrop.io` |
| Authentication | Put the API key in the `x-api-key` header. You can only read apps in the key's project. App IDs from other projects return `404`. |
| ID format | A string of up to 64 letters, digits, `_`, and `-`. |
| Timestamps | `createdAt` is epoch milliseconds. |

***

## Endpoints

Paths are relative to the Base URL.

| Method | Path | Scope | Description |
| - | - | - | - |
| `GET` | `/apps` | `app:read` | [List apps](#list-apps) |
| `GET` | `/apps/{appId}` | `app:read` | [Get an app](#get-an-app) |

***

## App Object

| Field | Type | Description |
| - | - | - |
| `_id` | string | App ID |
| `title` | string | App name |
| `platform` | string | App platform: `android`, `ios`, `web`, `api`, `flutter`, `react`, or `unity` |
| `createdAt` | number | When the app was registered |

Settings such as the app key used to initialize the SDK aren't included in the response.

***

## List Apps

Returns the project's apps one page at a time. The order is mostly the order they were registered, but older apps may be out of order. Don't rely on the order. Use `next` to read the following pages.

### Request

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

Requires the `app:read` scope.

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | :-: | - | - |
| `limit` | number | - | `20` | Number of apps per page (1–120) |
| `next` | string | - | - | Cursor for the next page. Pass the `next` value from the previous response as is. Omit it for the first page. |

### Request Example

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

### Response Example

Returns `200` with `items` (the apps) and `next` (the cursor for the next page). If there's no `next`, this is the last page.

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

***

## Get an App

Returns one app.

### Request

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

Requires the `app:read` scope.

### Request Example

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

### Response

Returns `200` with an [app object](#app-object).

### Errors

* `404 PROJECT_APP_NOT_FOUND`: The app doesn't exist or belongs to another project.

***

## Error Handling

Error responses include `statusCode`. Errors whose `errorCode` in the table below isn't `-` also include `errorCode`. Handle errors by `errorCode`, or by `statusCode` when there's no `errorCode`. For request format errors (`VALIDATION_FAILED`), `path` in `detail.errors[]` shows where the problem is.

| Status | `errorCode` | Cause |
| - | - | - |
| `400` | `VALIDATION_FAILED` | The app ID or `next` has an invalid format, `limit` is out of range, or you sent an unknown query parameter. |
| `401` | - | The API key is missing, invalid, or revoked. |
| `403` | - | The key doesn't have the `app:read` scope. |
| `404` | `PROJECT_APP_NOT_FOUND` | The app doesn't exist or belongs to another project. |
| `429` | `TOO_MANY_CONCURRENT_REQUESTS` | The server is busy. Wait for the number of seconds in the `Retry-After` header, then resend. You can get this error even if you send requests one at a time. |
| `502` | - | Internal server communication failed. |


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