Update a settings object

Latest Dynatrace
Reference
Published Oct 13, 2026

Update a settings object in Dynatrace with the App Settings API, using optimistic locking and optional admin access to change stored values.


PUT	SaaS	`https://{your-environment-id}.apps.dynatrace.com/v2/objects/{object-id}`

Overview

You provide the object ID path parameter and the required optimistic-locking-version query parameter, plus optional admin-access. In the request body, you send value and can place items with insertAfter or insertBefore; the response confirms success.

Authentication

To execute this request, you need a platform token or OAuth access token with app-settings:objects:write scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

Parameter	Type	Description	In	Required
object-id	string	The ID of the required settings object	path	Required
optimistic-locking-version	string	The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It is generated upon retrieval (GET requests). If set on update (PUT request) or deletion, the update/deletion will be allowed only if there wasn't any change between the retrieval and the update.	query	Required
admin-access	boolean	If set to true and user has app-settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects	query	Optional
body	AppSettingsObjectUpdate	The JSON body of the request. Contains updated parameters of the settings object.	body	Required

Request body objects

The `AppSettingsObjectUpdate` object

An update of a settings object.

Element Type Description Required

value

Element	Type	Description	Required
value	AppSettingsValue	The value of the setting. It defines the actual values of settings' parameters. The actual content depends on the object's schema.	Required
insertAfter	string	The position of the updated object. The new object will be moved behind the specified one. insertAfter and insertBefore are evaluated together and only one of both can be set. If `null` and insertBefore 'null', the existing object keeps the current position. If set to empty string, the updated object will be placed in the first position. Only applicable for objects based on schemas with ordered objects (schema's ordered parameter is set to `true`).	Optional
insertBefore	string	The position of the updated object. The new object will be moved in front of the specified one. insertAfter and insertBefore are evaluated together and only one of both can be set. If `null` and insertAfter 'null', the existing object keeps the current position. If set to empty string, the updated object will be placed in the last position. Only applicable for objects based on schemas with ordered objects (schema's ordered parameter is set to `true`).	Optional

AppSettingsValue

The value of the setting.

It defines the actual values of settings' parameters.

The actual content depends on the object's schema.

Required

insertAfter

string

The position of the updated object. The new object will be moved behind the specified one.

insertAfter and insertBefore are evaluated together and only one of both can be set.

If null and insertBefore 'null', the existing object keeps the current position.

If set to empty string, the updated object will be placed in the first position.

Only applicable for objects based on schemas with ordered objects (schema's ordered parameter is set to true).

Optional

insertBefore

string

The position of the updated object. The new object will be moved in front of the specified one.

insertAfter and insertBefore are evaluated together and only one of both can be set.

If null and insertAfter 'null', the existing object keeps the current position.

If set to empty string, the updated object will be placed in the last position.

Only applicable for objects based on schemas with ordered objects (schema's ordered parameter is set to true).

Optional

The `AppSettingsValue` object

The value of the setting.

It defines the actual values of settings' parameters.

The actual content depends on the object's schema.

Request body JSON model

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.

{
  "value": {
    "autoMonitoring": true
  },
  "insertAfter": "Y2ktaGdyb3VwLTEyMythZjhjOThlOS0wN2I0LTMyMGEtOTQzNi02NTEyMmVlNWY4NGQ=",
  "insertBefore": "Y2ktaGdyb3VwLTEyMythZjhjOThlOS0wN2I0LTMyMGEtOTQzNi02NTEyMmVlNWY4NGQ="
}

Response

Response codes

Code	Type	Description
200	AppSettingsUpdateResponse	Success
400	ErrorResponse	Failed. The input is invalid.
403	ErrorResponse	Failed. Forbidden.
404	ErrorResponse	Failed. The requested resource doesn't exist.
409	-	-
429	-	-
503	-	-
4XX	-	-
5XX	-	-

Response body objects

The `AppSettingsUpdateResponse` object

The response to an update request.

Element	Type	Description
version	string	The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It is generated upon retrieval (GET requests). If set on update (PUT request) or deletion, the update/deletion will be allowed only if there wasn't any change between the retrieval and the update.

Element

Type

Description

version

string

The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users.

It is generated upon retrieval (GET requests). If set on update (PUT request) or deletion, the update/deletion will be allowed only if there wasn't any change between the retrieval and the update.

The `ErrorResponse` object

Element	Type	Description
error	Error	Standard error response

The `Error` object

Standard error response

Element	Type	Description
code	number	The error code (HTTP response)
message	string	The error message
retryAfterSeconds	number	Number of seconds a request can be retried after a 'too many requests' error response.
details	ErrorDetails	Optional details of the error

The `ErrorDetails` object

Optional details of the error

Element	Type	Description
errorRef	string	reference to the error occurrence in the internal self-monitoring, logging, etc.
constraintViolations	ConstraintViolation[]	A list of constraint violations of input parameters (path, query, request body)
missingScopes	string[]	In case of a 403 - Forbidden response, a list of missing scopes necessary to successfully execute the request

The `ConstraintViolation` object

Contains information about a constraint violation caused by invalid input.

Element	Type	Description
path	string	The path of the parameter that caused the constraint violation
message	string	The constraint violation description message
parameterLocation	string	Describes the general location of the violating parameter The element can hold these values `PATH` `QUERY` `HEADER` `PAYLOAD_BODY`

Response body JSON models

{
  "version": "Y2ktaGdyb3VwLTEyMythZjhjOThlOS0wN2I0LTMyMGEtOTQzNi02NTEyMmVlNWY4NGQ="
}

{
  "error": {
    "code": 1,
    "message": "string",
    "retryAfterSeconds": 1,
    "details": {
      "errorRef": "string",
      "constraintViolations": [
        {
          "path": "string",
          "message": "string",
          "parameterLocation": "PATH"
        }
      ],
      "missingScopes": [
        "string"
      ]
    }
  }
}

PUT

SaaS

https://{your-environment-id}.apps.dynatrace.com/v2/objects/{object-id}

Parameters

Parameter	Type	Description	In	Required
object-id	string	The ID of the required settings object	path	Required
optimistic-locking-version	string	The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It is generated upon retrieval (GET requests). If set on update (PUT request) or deletion, the update/deletion will be allowed only if there wasn't any change between the retrieval and the update.	query	Required
admin-access	boolean	If set to true and user has app-settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects	query	Optional
body	AppSettingsObjectUpdate	The JSON body of the request. Contains updated parameters of the settings object.	body	Required

Request body objects

The `AppSettingsObjectUpdate` object

An update of a settings object.

Element Type Description Required

value

Element	Type	Description	Required
value	AppSettingsValue	The value of the setting. It defines the actual values of settings' parameters. The actual content depends on the object's schema.	Required
insertAfter	string	The position of the updated object. The new object will be moved behind the specified one. insertAfter and insertBefore are evaluated together and only one of both can be set. If `null` and insertBefore 'null', the existing object keeps the current position. If set to empty string, the updated object will be placed in the first position. Only applicable for objects based on schemas with ordered objects (schema's ordered parameter is set to `true`).	Optional
insertBefore	string	The position of the updated object. The new object will be moved in front of the specified one. insertAfter and insertBefore are evaluated together and only one of both can be set. If `null` and insertAfter 'null', the existing object keeps the current position. If set to empty string, the updated object will be placed in the last position. Only applicable for objects based on schemas with ordered objects (schema's ordered parameter is set to `true`).	Optional

AppSettingsValue

The value of the setting.

It defines the actual values of settings' parameters.

The actual content depends on the object's schema.

Required

insertAfter

string

The position of the updated object. The new object will be moved behind the specified one.

insertAfter and insertBefore are evaluated together and only one of both can be set.

If null and insertBefore 'null', the existing object keeps the current position.

If set to empty string, the updated object will be placed in the first position.

Only applicable for objects based on schemas with ordered objects (schema's ordered parameter is set to true).

Optional

insertBefore

string

The position of the updated object. The new object will be moved in front of the specified one.

insertAfter and insertBefore are evaluated together and only one of both can be set.

If null and insertAfter 'null', the existing object keeps the current position.

If set to empty string, the updated object will be placed in the last position.

Only applicable for objects based on schemas with ordered objects (schema's ordered parameter is set to true).

Optional

The `AppSettingsValue` object

The value of the setting.

It defines the actual values of settings' parameters.

The actual content depends on the object's schema.

Request body JSON model

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.

{
  "value": {
    "autoMonitoring": true
  },
  "insertAfter": "Y2ktaGdyb3VwLTEyMythZjhjOThlOS0wN2I0LTMyMGEtOTQzNi02NTEyMmVlNWY4NGQ=",
  "insertBefore": "Y2ktaGdyb3VwLTEyMythZjhjOThlOS0wN2I0LTMyMGEtOTQzNi02NTEyMmVlNWY4NGQ="
}

Response

Response codes

Code	Type	Description
200	AppSettingsUpdateResponse	Success
400	ErrorResponse	Failed. The input is invalid.
403	ErrorResponse	Failed. Forbidden.
404	ErrorResponse	Failed. The requested resource doesn't exist.
409	-	-
429	-	-
503	-	-
4XX	-	-
5XX	-	-

Response body objects

The `AppSettingsUpdateResponse` object

The response to an update request.

Element	Type	Description
version	string	The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It is generated upon retrieval (GET requests). If set on update (PUT request) or deletion, the update/deletion will be allowed only if there wasn't any change between the retrieval and the update.

Element

Type

Description

version

string

The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users.

It is generated upon retrieval (GET requests). If set on update (PUT request) or deletion, the update/deletion will be allowed only if there wasn't any change between the retrieval and the update.

The `ErrorResponse` object

Element	Type	Description
error	Error	Standard error response

The `Error` object

Standard error response

Element	Type	Description
code	number	The error code (HTTP response)
message	string	The error message
retryAfterSeconds	number	Number of seconds a request can be retried after a 'too many requests' error response.
details	ErrorDetails	Optional details of the error

The `ErrorDetails` object

Optional details of the error

Element	Type	Description
errorRef	string	reference to the error occurrence in the internal self-monitoring, logging, etc.
constraintViolations	ConstraintViolation[]	A list of constraint violations of input parameters (path, query, request body)
missingScopes	string[]	In case of a 403 - Forbidden response, a list of missing scopes necessary to successfully execute the request

The `ConstraintViolation` object

Contains information about a constraint violation caused by invalid input.

Element	Type	Description
path	string	The path of the parameter that caused the constraint violation
message	string	The constraint violation description message
parameterLocation	string	Describes the general location of the violating parameter The element can hold these values `PATH` `QUERY` `HEADER` `PAYLOAD_BODY`

Response body JSON models

{
  "version": "Y2ktaGdyb3VwLTEyMythZjhjOThlOS0wN2I0LTMyMGEtOTQzNi02NTEyMmVlNWY4NGQ="
}

{
  "error": {
    "code": 1,
    "message": "string",
    "retryAfterSeconds": 1,
    "details": {
      "errorRef": "string",
      "constraintViolations": [
        {
          "path": "string",
          "message": "string",
          "parameterLocation": "PATH"
        }
      ],
      "missingScopes": [
        "string"
      ]
    }
  }
}

Update a settings object

Overview

Authentication

Parameters

Request body objects

The AppSettingsObjectUpdate object

The AppSettingsValue object

Request body JSON model

Response

Response codes

Response body objects

The AppSettingsUpdateResponse object

The ErrorResponse object

The Error object

The ErrorDetails object

The ConstraintViolation object

Response body JSON models

Update a settings object

Overview

Authentication

Parameters

Request body objects

The AppSettingsObjectUpdate object

The AppSettingsValue object

Request body JSON model

Response

Response codes

Response body objects

The AppSettingsUpdateResponse object

The ErrorResponse object

The Error object

The ErrorDetails object

The ConstraintViolation object

Response body JSON models

The `AppSettingsObjectUpdate` object

The `AppSettingsValue` object

The `AppSettingsUpdateResponse` object

The `ErrorResponse` object

The `Error` object

The `ErrorDetails` object

The `ConstraintViolation` object

The `AppSettingsObjectUpdate` object

The `AppSettingsValue` object

The `AppSettingsUpdateResponse` object

The `ErrorResponse` object

The `Error` object

The `ErrorDetails` object

The `ConstraintViolation` object