# App Management API The app management API allows the ability to obtain and update app details as well as creating and deleting apps. ## Before you get started 1. Review and accept the Chartboost App Disclosures on the [User Access Management](https://platform.chartboost.com/company/access-management) page in the [Chartboost platform](https://platform.chartboost.com/). 2. Complete the [API Access & Authentication](/en/advertising/reference/api-overview/#version-5-api-access-setup) process. You will not be able to create or manage your apps programmatically until the above steps are completed. ## Endpoints | Endpoint | Description | | -------------------------------------------------- | ---------------------- | | [`GET /v5/apps`](#get-a-list-of-apps) | Get a list of apps | | [`POST /v5/apps`](#create-a-new-app) | Create a new app | | [`GET /v5/apps/{app_id}`](#get-a-single-app-by-id) | Get a single app by ID | | [`DELETE /v5/apps/{app_id}`](#delete-an-app) | Delete an app by ID | | [`PATCH /v5/apps/{app_id}`](#update-an-app) | Update an app by ID | *** ### Get a list of apps `GET /v5/apps` Retrieves all the apps belonging to a company. **Required Headers** ```text Authorization: Bearer {access-token} Content-Type: application/json;charset=UTF-8 ``` **Optional Request Parameters** | Field | Type | Description | | :--------------- | :----- | :------------------------------------------------------- | | keyword_filter | string | A keyword to filter by. Applies to app name or nickname. | | platform_filters | string | Filter by platform (“android”, “ios”, “amazon”) | | direction | string | Sort direction (“asc”, “desc”) | | page | int | Requested page number | | limit | int | Amount of items per page. (default = 25) | Request Example: ```text GET /v5/apps?page=1&limit=5 HTTP/1.1 Host: api.chartboost.com Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/json;charset=UTF-8 ``` **Response Parameters** | Field | Description | | :--------------------------- | :------------ | | `id` | The app's ID. | | `nickname` | A given nickname for the app. This does not have to match the app name in the app store. | | `icon` | The official icon URL extracted from the app store. | | `platform` | Specifies the app platform `ios`, `android`, or `amazon`. | | `is_live` | Indicates whether the app is live in the app store or not. | | `store_app_id` | Indicates the app ID in the app store. | | `name` | The name of the app in the app-store. | | `publishing_application` | States details on whether the app has been approved or rejected by Chartboost, reasons for rejection, and date reviewed. | | `metadata` | States number of ad locations for a given ad format. | 200 OK Successful Response Example: ```json { "items": [ { "id": "64054c7decf2fc7b954e98d2", "nickname": "Android Test App", "icon": "https://play-lh.googleusercontent.com/Gz9uP4jwKhNb942ykXrIuGfza3a31p6GpJ2YdPStC7CivobAHKayDSR5QSrruauZZ1k=s180", "platform": "android", "is_live": true, "store_app_id": "com.kathleenOswald.solitaireGooglePlay", "name": "Solitaire + Card Game by Zynga", "publishing_application": { "status": "Rejected", "created_at": 1683312886, "reviewed_by": "624b2f1471a86307cc1621bc", "reviewed_at": 1683531176, "reviewer_notes": "", "reject_reason": "dau", "reject_detail": "low-dau", "rejected_at": 1683531176 }, "metadata": { "ad_location_counts": { "interstitial": 7, "rewarded": 1, "banner": 0 } } } ], "page": 1, "limit": 5, "total": 1 } ``` 400 Validation Error Example: ```json { "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } ``` *** ### Create a new App `POST /v5/apps` Creates an app from the given input data and retrieves a partial representation of the created app. **Required Headers** ```text Authorization: Bearer {access-token} Content-Type: application/json;charset=UTF-8 ``` **Request Parameters** | Field | Type | Required/Optional | Description | | :--------------------------- | :-------- | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `nickname` | string | Required | A given nickname for the app. This does not have to match the app name in the app store. | | `name` | string | Optional | The name of the app in the app-store. If not provided, this value will automatically be set once the app is live in an app store. | | `orientations` | string\[] | Required | An array of supported app orientations. Values accepted are `landscape` and `portrait`. | | `default_orientation` | string | Optional | Required whenever the `orientations` field specifies both `landscape` and `portrait` at the same time. In such a case, the `default_orientation` field will specify which one is to be treated as default. | | `is_live` | boolean | Required | Indicates whether the app is live in the app store or not. | | `store_app_id` | string | Optional | This field is always required when `is_live = true`. It is used to indicate the app ID in the app store. | | `store_app_url` | string | Optional | This field is always required when `is_live = true`. It is used to indicate the app’s official app store URL. | | `store_bundle_id` | string | Optional | This field is always required when `is_live = true`. it is used to indicate the app’s official bundle ID in the app store. | | `is_test_mode_on` | boolean | Required | Indicates whether the app is in `test_mode` or not. | | `test_mode_duration` | integer | Optional | Specifies the duration in minutes until test mode expires. This field is optional and only effective when `is_test_mode_on = true`. If test mode is set true and this field is not provided, then test mode will be enabled indefinitely. | | `is_directed_at_kids_under_13` | string | Required | Specifies whether the app is directed at kids under 13 or not, the value is required and must be either `YES` or `NO` to adhere to COPPA Regulations. | | `platform` | string | Required | Specifies the app platform `ios`, `android`, or `amazon`. | Request Example: ```text POST /v5/apps HTTP/1.1 Host: api.chartboost.com Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/json;charset=UTF-8 { "nickname": "example app", "orientations": [ "portrait" ], "is_live": true, "is_test_mode_on": false, "store_app_id": "com.chartboost.example", "store_app_url": "https://play.google.com/store/apps/example", "store_bundle_id": "com.chartboost.example", "is_directed_at_kids_under_13": "NO", "platform": "android" } ``` 200 OK Successful Response Example: ```json { "id": "64054c7decf2fc7b954e98d2", "nickname": "example app", "orientations": [ "portrait" ], "default_orientation": "portrait", "platform": "android", "is_live": true, "signature": "{app signature}", "is_coppa_disclosure_read": true, "is_sdk_active": false, "is_test_mode_on": false, "store_app_id": "com.chartboost.com", "store_app_url": "https://play.google.com/store/apps/example", "store_bundle_id": "com.chartboost.example", "is_directed_at_kids_under_13": "NO" } ``` *** ### Get a single app by ID `GET /v5/apps/{app_id}` Retrieves a single app for the given ID if it exists. **Required Headers** ```text Authorization: Bearer {access-token} Content-Type: application/json;charset=UTF-8 ``` Request Example ```text GET /v5/apps/64054c7decf2fc7b954e98d2 HTTP/1.1 Host: api.chartboost.com Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/json;charset=UTF-8 ``` **Response Parameters** | Field | Description | | :--------------------------- | :------------ | | `id` | The app's ID. | | `nickname` | A given nickname for the app. This does not have to match the app name in the app store. | | `orientations` | An array of supported app orientations. | | `default_orientation` | Specifies which orientation is to be treated as default when both orientations are listed in `orientations`. | | `platform` | Specifies the app platform `ios`, `android`, or `amazon`. | | `is_live` | Indicates whether the app is live in the app store or not. | | `signature` | The app's signature ID. | | `is_coppa_disclosure_read` | States whether user has accepted the Chartboost App disclosure. | | `is_sdk_active` | States whether the SDK is active or not. | | `is_test_mode_on` | Indicates whether the app is in test mode. | | `test_mode_duration` | Specifies the duration in minutes until test mode expires. This field is only effective when `is_test_mode_on = true`. If test mode is set true and this field is not provided, then test mode will be enabled indefinitely. | | `name` | The name of the app in the app-store. | | `icon` | The official icon URL extracted from the app store. | | `store_app_id` | Indicates the app ID in the app store. | | `store_app_url` | Indicates the app’s official app store URL. | | `store_bundle_id` | Indicate the app’s official bundle ID in the app store.| | `publishing_application` | States details on whether the app has been approved or rejected by Chartboost, reasons for rejection, and date reviewed. | | `app_ads_txt_status` | Indicates the app's app-ads.txt status. | | `metadata` | States number of ad locations for a given ad format. | | `is_directed_at_kids_under_13` | Specifies whether the app is directed at kids under 13 or not. | 200 OK Successful Response Example: ```json { "id": "64054c7decf2fc7b954e98d2", "nickname": "android_test_app", "orientations": [ "landscape", "portrait" ], "default_orientation": "landscape", "platform": "android", "is_live": false, "signature": "05908d540aecdb0d6eae6f43d5806769dfa33b2c", "is_coppa_disclosure_read": true, "is_sdk_active": false, "is_test_mode_on": true, "test_mode_duration": null, "name": null, "icon": null, "store_app_id": null, "store_app_url": null, "store_bundle_id": null, "publishing_application": { "status": "Approved", "created_at": 1699652507, "reviewed_by": "automatic_review", "reviewed_at": 1699652507, "reviewer_notes": "", "reject_reason": null, "reject_detail": null, "rejected_at": null }, "app_ads_txt_status": null, "metadata": { "ad_location_counts": { "interstitial": 0, "rewarded": 1, "banner": 0 } }, "is_directed_at_kids_under_13": "NO" } ``` 404 Not Found Example Error: ```json { "detail": [ { "msg": "There is no app with ID 64054c7decf2fc7b954e98d2", "type": "not_found" } ] } ``` *** ### Delete an App `DELETE /v5/apps/{app_id}` Deletes the app identified by the given `app_id`. This operation performs a soft deletion of the app i.e., it just marks the app as deleted. **Required Headers** ```text Authorization: Bearer {access-token} Content-Type: application/json;charset=UTF-8 ``` Request Example: ```text DELETE /v5/apps/64054c7decf2fc7b954e98d2 HTTP/1.1 Host: api.chartboost.com Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/json;charset=UTF-8 ``` 204 Successful Response Example: ```text 204 No Content ``` *** ### Update an App `PATCH /v5/apps/{app_id}` Updates the app identified by the given app_id and retrieves an updated version of the given app data payload. **Required Headers** ```text Authorization: Bearer {access-token} Content-Type: application/json;charset=UTF-8 ``` **Request Parameters** | Field | Type | Required/Optional | Description | | :--------------------------- | :-------- | :---------------- | :------------ | | `orientations` | string\[] | Optional | An array of supported app orientations. Values accepted are `landscape` and `portrait`. | | `default_orientation` | string | Optional | Required whenever the `orientations` field specifies both `landscape` and `portrait` at the same time. In such a case, the `default_orientation` field will specify which one is to be treated as default. | | `is_live` | boolean | Optional | Indicates whether the app is live in the app store or not. Cannot be changed from `true` to `false`. | | `store_app_id` | string | Optional | This field is always required when `is_live = true`. Indicates the app ID in the app store. Cannot be changed to `null`. | | `store_app_url` | string | Optional | This field is always required when `is_live = true`. Indicates the app’s official app store URL. Cannot be changed to `null`. | | `store_bundle_id` | string | Optional | This field is always required when `is_live = true`. Indicate the app’s official bundle ID in the app store. Cannot be changed to `null`. | | `is_test_mode_on` | boolean | Optional | Indicates whether the app is in `test_mode` or not. | | `test_mode_duration` | integer | Optional | Specifies the duration in minutes until test mode expires. This field is optional and only effective when `is_test_mode_on = true`. If test mode is set true and this field is not provided, then test mode will be enabled indefinitely. | | `is_directed_at_kids_under_13` | string | Optional | Specifies whether the app is directed at kids under 13 or not, the value is required and must be either `YES` or `NO` to adhere to COPPA Regulations. | Request Example: ```text PATCH /v5/apps/64054c7decf2fc7b954e98d2 HTTP/1.1 Host: api.chartboost.com Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/json;charset=UTF-8 { "nickname": "example app", "orientations": [ "portrait", "landscape" ], "default_orientation": "landscape" } ``` **Response Parameters** | Field | Description | | :--------------------------- | :------------ | | `nickname` | A given nickname for the app. This does not have to match the app name in the app store. | | `name` | The name of the app in the app-store. | | `icon` | The official icon URL extracted from the app store. | | `publishing_application` | States details on whether the app has been approved or rejected by Chartboost, reasons for rejection, and date reviewed. | | `is_sdk_active` | States whether the SDK is active or not. | | `is_coppa_disclosure_read` | States whether user has accepted the Chartboost App disclosure. | | `platform` | Specifies the app platform `ios`, `android`, or `amazon`. | | `orientations` | An array of supported app orientations. | | `default_orientation` | Specifies which orientation is to be treated as default when both orientations are listed in `orientations`. | | `is_live` | Indicates whether the app is live in the app store or not. | | `store_app_id` | Indicates the app ID in the app store. | | `store_app_url` | Indicates the app’s official app store URL. | | `store_bundle_id` | Indicate the app’s official bundle ID in the app store.| | `is_test_mode_on` | Indicates whether the app is in test mode. | | `test_mode_duration` | Specifies the duration in minutes until test mode expires. This field is only effective when `is_test_mode_on = true`. If test mode is set true and this field is not provided, then test mode will be enabled indefinitely. | | `is_directed_at_kids_under_13` | Specifies whether the app is directed at kids under 13 or not. | 200 OK Successful Response Example: ```json { "id": "64054c7decf2fc7b954e98d2", "nickname": "example app", "orientations": [ "portrait", "landscape" ], "default_orientation": "landscape", "platform": "android", "is_live": true, "signature": "{app signature}", "is_coppa_disclosure_read": true, "is_sdk_active": false, "is_test_mode_on": false, "store_app_id": "com.chartboost.com", "store_app_url": "https://play.google.com/store/apps/example", "store_bundle_id": "com.chartboost.example", "is_directed_at_kids_under_13": "NO", "publishing_application": { "status": "Approved", "created_at": 1686315670, "reviewed_by": "automatic_review", "reviewed_at": 1686315670, "reviewer_notes": "", "reject_reason": null, "reject_detail": null, "rejected_at": null } } ```