/i/app_users/update

Endpoint

/i/app_users/update

Overview

Update app user documents by query using MongoDB update modifiers.

Authentication

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

Permissions

• Requires write-level app access.

Request Parameters

Parameter	Type	Required	Description
api_key	String	Yes (or use auth_token)	Dashboard API authentication key.
auth_token	String	Yes (or use api_key)	Dashboard auth token.
app_id	String	Yes	Target app ID.
query	JSON String (Object)	Yes	MongoDB query selecting users to update.
update	JSON String (Object)	Yes	MongoDB update modifiers ($set, $unset, $inc, etc.).
force	Boolean/String	No	Required when query matches more than one user.

update Object Structure

Field	Type	Required	Description
$set	Object	No	Assigns field values.
$unset	Object	No	Removes fields.
$inc	Object	No	Increments numeric fields.
$push / $pull	Object	No	Updates array fields.
other Mongo modifiers	Object	No	Allowed when key starts with $.

Examples

Example 1: Update one user property

/i/app_users/update?api_key=YOUR_API_KEY&app_id=64b0ac10c2c3ce0012dd1001&query={"uid":"1"}&update={"$set":{"name":"Jane"}}

{
  "result": "User Updated"
}

Response

Success Response

{
  "result": "User Updated"
}

Response Fields

Field	Type	Description
result	String	Update status message.

Error Responses

Status Code: 400 Bad Request

{
  "result": "Missing parameter \"app_id\""
}

Status Code: 400 Bad Request

{
  "result": "Missing parameter \"query\""
}

Status Code: 400 Bad Request

{
  "result": "Missing parameter \"update\""
}

Status Code: 400 Bad Request

{
  "result": "Could not parse parameter \"update\": {bad-json}"
}

Status Code: 400 Bad Request

{
  "result": "Could not parse parameter \"query\": {bad-json}"
}

Status Code: 400 Bad Request

{
  "result": "Parameter \"update\" cannot be empty"
}

Status Code: 400 Bad Request

{
  "result": "No users matching criteria"
}

Status Code: 400 Bad Request

{
  "result": "This query would update more than one user"
}

Status Code: 400 Bad Request

{
  "result": "Unkown modifier name in {\"name\":\"Alex\"} for {\"uid\":\"1\"}"
}

Status Code: 400 Bad Request

{
  "result": "Missing parameter \"api_key\" or \"auth_token\""
}

Behavior

Behavior Modes

Mode	Trigger	Processing Path	Response Shape
Single-user update	Query matches exactly one user	Validates modifiers, updates matching user document.	Wrapped string: { "result": "User Updated" }
Multi-user update	Query matches more than one user and force is provided	Applies updateMany to all matched users.	Wrapped string: { "result": "User Updated" }
Multi-user blocked	Query matches more than one user and force is missing	Update is rejected before write.	Wrapped error string: { "result": "This query would update more than one user" }

Impact on Other Data

• Triggers plugin listeners for app-user updates, so plugin-specific user data may be updated as part of the same operation.

Limitations

• Non-modifier update objects are rejected (update keys must start with $).
• Multi-user updates require explicit force.

Related Endpoints

• App Users - Create
• App Users - Delete

Implementation details

Database Collections

Collection	Used for	Data touched by this endpoint
countly.members	Authentication and permission validation	Reads member identity and app-level write permissions.
countly.app_users{appId}	User query and update target	Counts matched users and applies MongoDB modifier updates to matching documents.