App Management API

Getting Started

Before you get started:

Make sure you review and accept the Chartboost App Disclosures on the User Access Management page in the Chartboost Dashboard.
Make sure you have read and understood the section on API Access & Authentication

You will not be able to create or manage your apps programmatically until the above steps are completed.

Endpoints

Endpoint	Description
`GET /v4/apps`	Get a list of apps
`POST /v4/apps`	Create a new app
`GET /v4/apps/{app_id}`	Get a single app by ID
`DELETE /v4/apps/{app_id}`	Delete an app by ID
`PATCH /v4/apps/{app_id}`	Update an app by ID

Get a list of apps

GET /v4/apps

Retrieves all the apps belonging to a company.

Required Headers

Authorization: Bearer {access-token}
Content-Type: application/json;charset=UTF-8

Optional Parameters

Field	Type	Description
keyword_filter	string	A keyword to filter by. Applies to app name or nickname.
platform_filter	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:

GET /v4/apps?page=1&limit=5 HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

200 OK Successful Response Example:

{
  items: [
    {
      "id": "string",
      "nickname": "string",
      "platform": "string",
      "is_live": boolean,
      "name": "string",
      "icon": "string",
      "store_app_id": "string"
    },
    ...
  ],
  page: "integer",
  limit: "integer",
  total: "integer"
}

400 Validation Error Example:

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Create a new App

POST /v4/apps

Creates an app from the given input data and retrieves a partial representation of the created app.

Required Headers

Authorization: Bearer {access-token}
Content-Type: application/json;charset=UTF-8

Request Body Fields

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:

GET /v4/apps HTTP/1.1
Host: api.chartboost.com
Authorization: Basic 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:

{
    "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 /v4/apps/{app_id}

Retrieves a single app for the given ID if it exists.

Required Headers

Authorization: Bearer {access-token}
Content-Type: application/json;charset=UTF-8

Request Example

GET /v4/apps/64054c7decf2fc7b954e98d2 HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

200 OK Successful Response Example:

{
    "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"
}

404 Not Found Example Error:

{
    "detail": [
        {
            "msg": "There is no app with ID 64054c7decf2fc7b954e98d2",
            "type": "not_found"
        }
    ]
}

Delete an App

DELETE /v4/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

Authorization: Bearer {access-token}
Content-Type: application/json;charset=UTF-8

Request Example:

DELETE /v4/apps/64054c7decf2fc7b954e98d2 HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

204 Successful Response Example:

204 No Content

Update an App

PATCH /v4/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

Authorization: Bearer {access-token}
Content-Type: application/json;charset=UTF-8

Special Considerations

Immutable fields—the following fields cannot be updated:

platform
is_coppa_disclosure_read
is_sdk_active
publishing_application
name
icon

Conditionally mutable fields—the following fields can only be updated under certain conditions:

is_live - Cannot be changed from true to false
store_app_id - Cannot be changed to null
store_app_url - Cannot be changed to null
store_bundle_id - Cannot be changed to null

Request Example:

PATCH /v4/apps/64054c7decf2fc7b954e98d2 HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

{
  "nickname": "example app",
  "orientations": [
    "portrait",
    "landscape"
  ],
  "default_orientation": "landscape"
}

200 OK Successful Response Example:

{
    "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"
}