Skip to main content
Version: 25.03

/i/apps/update/plugins

Endpoint​

/i/apps/update/plugins

Overview​

Update the app-level configuration of one or more plugins. Each key in args is a plugin (or settings section) name and its value is the configuration to store for that app.

Authentication​

Pass api_key or auth_token as a query parameter, or send countly-token as a header. See Authentication.

Permissions​

  • Global admin, or admin of the target app.

Request Parameters​

ParameterTypeRequiredDescription
api_keyStringYes (or use auth_token)Dashboard API authentication key.
auth_tokenStringYes (or use api_key)Dashboard auth token.
app_idStringYesTarget app ID. Must be exactly 24 characters.
argsJSON String (Object)YesMap of plugin name to its new app-level configuration.

args Object Structure​

FieldTypeRequiredDescription
[pluginName]ObjectNoNew configuration for that plugin or settings section. Use one key per plugin to update. If args is an empty object, nothing is changed.

Always send args, and make sure it is a valid JSON object (not an array or a plain string), URL-encoded when passed in the query string. Include only the plugins or settings sections you want to change.

Examples​

Example 1: Update a settings section that is not a plugin​

/i/apps/update/plugins?api_key=YOUR_API_KEY&app_id=64b0ac10c2c3ce0012dd1001&args={"my_section":{"enabled":true}}

Example 2: Update a plugin that handles its own config​

/i/apps/update/plugins?api_key=YOUR_API_KEY&app_id=64b0ac10c2c3ce0012dd1001&args={"push":{"rate":{"rate":100,"period":60}}}

Response​

Success Response​

Example 1 (key is stored as sent and echoed back):

{
  "_id": "64b0ac10c2c3ce0012dd1001",
  "plugins": {
    "my_section": {
      "enabled": true
    }
  }
}

Example 2 (the push plugin stores the config itself and returns no value, so plugins is empty and result is an empty string):

{
  "_id": "64b0ac10c2c3ce0012dd1001",
  "plugins": {},
  "result": ""
}

If no keys were supplied in args:

{
  "result": "Nothing changed"
}

Response Fields​

FieldTypeDescription
_idStringApp ID.
pluginsObjectApplied configuration for each updated plugin.
resultStringPresent only when a plugin that handles its own config returned a non-object value; contains those values joined by newlines. It is an empty string when the plugin returned no value (for example push).

Error Responses​

Status Code: 400 Bad Request

{
  "result": "Error: Length of app_id is lower than min length value"
}

Status Code: 400 Bad Request (a plugin rejected its configuration)

{
  "errors": "Wrong credentials type"
}

Status Code: 400 Bad Request

{
  "result": "Couldn't update plugin: <reason>"
}

Status Code: 404 Not Found

{
  "result": "App not found"
}

Standard authentication/authorization errors from app admin validation can also be returned.

Behavior​

  • Loads the app by app_id; returns 404 if it does not exist.
  • For every key in args that is an enabled plugin, the update is first offered to that plugin, which can validate or transform the config.
  • If a plugin handles the update, it stores the config itself and the generic app_config_updated log is not written (the plugin may write its own, for example push writes plugin_push_config_updated). Push only acts on its known keys (such as rate); unknown keys are ignored.
  • If no plugin handles the update, or the key is not an enabled plugin, the value is stored in the app document under plugins.<name> and an app_config_updated system log entry is written with the config before and after.
Implementation details

Database Collections

CollectionUsed forData touched by this endpoint
countly.appsApp plugin configReads the app and sets plugins.<name>.