App Management API

Getting Started

Before you get started:

  1. Make sure you review and accept the Chartboost App Disclosures on the User Access Management page in the Chartboost platform.
  2. 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

EndpointDescription
GET /v4/appsGet a list of apps
POST /v4/appsCreate 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

FieldTypeDescription
keyword_filterstringA keyword to filter by. Applies to app name or nickname.
platform_filtersstringFilter by platform (“android”, “ios”, “amazon”)
directionstringSort direction (“asc”, “desc”)
pageintRequested page number
limitintAmount 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

FieldTypeRequired/OptionalDescription
nicknamestringRequiredA given nickname for the app. This does not have to match the app name in the app store.
namestringOptionalThe 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.
orientationsstring[]RequiredAn array of supported app orientations. Values accepted are “landscape” and “portrait”.
default_orientationstringOptionalRequired 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_livebooleanRequiredIndicates whether the app is live in the app store or not.
store_app_idstringOptionalThis field is always required when is_live = True. It is used to indicate the app ID in the app store.
store_app_urlstringOptionalThis field is always required when is_live = True. It is used to indicate the app’s official app store URL.
store_bundle_idstringOptionalThis 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_onbooleanRequiredIndicates whether the app is in test_mode or not.
test_mode_durationintegerOptionalSpecifies 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_13stringRequiredSpecifies 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.
platformstringRequiredSpecifies 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"
}