Settings

• Reference

Manage Dynatrace settings through a schema-driven API for storing, querying, and maintaining configuration objects.

Managing settings objects

Create, retrieve, update, delete, reorder, and inspect settings objects. These endpoints also help you resolve effective settings values so you can understand how configuration is applied.

Managing access and ownership

Query and update permissions for settings objects, grant or revoke access for specific users and groups, and change ownership when needed. These endpoints support the security and governance workflows around shared configuration.

Reviewing change history

Retrieve revision history for settings objects to inspect how configuration changed over time. This helps with auditing, troubleshooting, and understanding previous updates.

Working with schemas

Discover and retrieve schema definitions that describe available settings types and their structure. These endpoints help clients understand which properties are supported and how settings objects must be shaped.

Supporting interactive editing

Use helper endpoints for validation, default generation, and value summaries during schema-based editing workflows. These operations are intended to support guided and interactive settings editors.

@dynatrace-sdk/client-settings

v1.0.5

Latest (V1)

npm install @dynatrace-sdk/client-settings

settingsHistoryClient

import { settingsHistoryClient } from '@dynatrace-sdk/client-settings';

listSettingsHistory

settingsHistoryClient.listSettingsHistory(config): Promise<RevisionDiffPage>

Gets the history of settings objects

Required scope: settings:objects:read

Returns revision history for settings objects, based on audit logs read from Grail with event.provider == 'SETTINGS' filter as described here.

You can use query parameters to sort, filter and paginate the results. If filter isn't provided, the API returns revisions from the last 2 weeks.

Parameters

Name	Type	Description
config.addFields	string	A list of fields to be included in the response. The provided set of fields extends the default set. Specify the required top-level fields, separated by commas (for example, revision,modificationInfo). Supported fields: revision, jsonPatch, jsonBefore, jsonAfter, objectId, type, schemaVersion, modificationInfo, schemaId, schemaDisplayName, summary, appId, source, ownerBefore, ownerAfter. Default fields: revision, modificationInfo.
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.filter	string	The filter parameter, as explained here. Nesting and unary operators aren't supported. Filtering is supported on the following fields: revision objectId schemaVersion modificationInfo.lastModifiedTime modificationInfo.lastModifiedBy If this parameter is omitted only revisions of the last 2 weeks are returned. If modificationInfo.lastModifiedTime doesn't specify a full range, it will be completed with current time minus 1 year for the missing lower bound or the current time for the upper bound. When the admin-access is set to false, this parameter is required for schemas with enabled owner based access control and must contain objectId field with operator ==.
config.pageKey	string	The cursor for the next page of results. You can find it in the nextPageKey field of the previous response. The first page is always returned if you don't specify the page-key query parameter. When the page-key is set to obtain subsequent pages, you must omit all other query parameters.
config.pageSize	number	The amount of settings objects in a single response payload. The maximal allowed page size is 5000. If not set, 100 is used.
config.schemaIds	string	Schema IDs to which the requested revisions belong as a comma-separated list. To load the first page, when the page-key isn't set, this parameter is required.
config.scope	string	Scope to which the requested revisions belong. To load the first page, when the page-key isn't set, this parameter is required.
config.sort	string	The sort parameter, as explained here Sorting is supported on the following fields: modificationInfo.lastModifiedTime

Returns

Return type	Status code	Description
RevisionDiffPage	200	Success.

Throws

Error Type	Error Message
NotFoundSchema	Failed. The specified schema wasn't found.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsHistoryClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsHistoryClient.listSettingsHistory();

settingsInteractiveEditingSupportClient

import { settingsInteractiveEditingSupportClient } from '@dynatrace-sdk/client-settings';

generateSchemaDefaultValue

settingsInteractiveEditingSupportClient.generateSchemaDefaultValue(config): Promise<SettingsDefaultObject>

Required scope: settings:schemas:read

Gets the default value of a settings schema.

Parameters

Name	Type	Description
config.schemaId*required	string	The ID of the requested schema.
config.schemaVersion	string	The requested version of the schema. If not set, the most recent version is assumed.
config.scope	string	The ID of the scope.

Returns

Return type	Status code	Description
SettingsDefaultObject	200	Success.

Throws

Error Type	Error Message
BadRequestInvalidInput	Failed. The input is invalid.
Forbidden	Failed. Forbidden.
NotFoundSchemaIdVersion	No schema could be found for the given schema-id and schema-version.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsInteractiveEditingSupportClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsInteractiveEditingSupportClient.generateSchemaDefaultValue(
    { schemaId: "..." },
  );

summarizeSettingsValue

settingsInteractiveEditingSupportClient.summarizeSettingsValue(config): Promise<SettingsObjectSummary>

Generate a summary for a specific settings value

Required scope: settings:schemas:read

Parameters

Name	Type	Description
config.body*required	SettingsObjectSummarize
config.schemaId*required	string	The ID of the required schema.

Returns

Return type	Status code	Description
SettingsObjectSummary	200	Success.

Throws

Error Type	Error Message
BadRequestInvalidInput	Failed. The input is invalid.
Forbidden	Failed. Forbidden.
NotFoundMultiObjectSchema	No multi-object schema could be found for the given schemaId and schemaVersion.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsInteractiveEditingSupportClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsInteractiveEditingSupportClient.summarizeSettingsValue(
    { schemaId: "...", body: { value: {} } },
  );

validateSettingsContainer

settingsInteractiveEditingSupportClient.validateSettingsContainer(config): Promise<ValidationResponse>

Validates the given settings container.

Required scope: settings:schemas:read

Validates the given settings container.

Parameters

Name	Type	Description
config.body*required	CustomContainerValidationRequest
config.schemaId*required	string	The ID of the schema.
config.schemaVersion	string	Version of the schema.
config.scope	string	The ID of the scope.
config.validatorId*required	string	The identifier of the validator.

Returns

Return type	Status code	Description
ValidationResponse	200	Validated. Details in the response body.

Throws

Error Type	Error Message
NotFoundValidator	Failed. Validator with the given identifier not found.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsInteractiveEditingSupportClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsInteractiveEditingSupportClient.validateSettingsContainer(
    {
      schemaId: "...",
      validatorId: "...",
      body: { value: {} },
    },
  );

validateSettingsProperty

settingsInteractiveEditingSupportClient.validateSettingsProperty(config): Promise<ValidationResponse>

Validates the given settings property.

Required scope: settings:schemas:read

Validates the given settings property value with the given custom validator.

Parameters

Name	Type	Description
config.body*required	CustomPropertyValidationRequest
config.schemaId*required	string	The ID of the schema.
config.schemaVersion	string	Version of the schema.
config.scope	string	The ID of the scope.
config.validatorId*required	string	The identifier of the validator.

Returns

Return type	Status code	Description
ValidationResponse	200	Validated. Details in the response body.

Throws

Error Type	Error Message
NotFoundValidator	Failed. Validator with the given identifier not found.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsInteractiveEditingSupportClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsInteractiveEditingSupportClient.validateSettingsProperty(
    { schemaId: "...", validatorId: "...", body: {} },
  );

settingsObjectsClient

import { settingsObjectsClient } from '@dynatrace-sdk/client-settings';

deleteSettingsObject

settingsObjectsClient.deleteSettingsObject(config): Promise<void>

Deletes the specified settings object

Required scope: settings:objects:write

Parameters

Name	Type	Description
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.objectId*required	string	The ID of the required settings object
config.optimisticLockingVersion*required	string	The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It's 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.
config.validateOnly	boolean	If true, the request runs only validation for the deletion of the settings object, without actually deleting it.

Returns

Return type	Status code	Description
void	204	Success. Response doesn't have a body.

Throws

Error Type	Error Message
BadRequestInvalidInput	Failed. The input is invalid.
Forbidden	Failed. Forbidden.
NotFoundResource	Failed. The requested resource doesn't exist.
ConflictingResource	Failed. Conflicting resource.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsObjectsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsObjectsClient.deleteSettingsObject({
    objectId: "...",
    optimisticLockingVersion: "...",
  });

getSettingsObject

settingsObjectsClient.getSettingsObject(config): Promise<SettingsObject>

Gets the specified settings object

Required scope: settings:objects:read

Gets the specified settings object. Properties of type secret will be included in plain text if the call originates from a serverless function of your app; they will have irreversibly masked values otherwise. This protects these secrets from leaking to users of your app or other third parties.

Parameters

Name	Type	Description
config.addFields	string	A list of fields to be included in the response. The provided set of fields extends the default set. Specify the required top-level fields, separated by commas (for example, summary,value). Supported fields: objectId, version, summary, searchSummary, scope, schemaId, schemaVersion, modificationInfo, resourceContext, value, owner, externalId. Default fields: objectId, version, scope, schemaId, schemaVersion, value, externalId.
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.objectId*required	string	The ID of the required settings object

Returns

Return type	Status code	Description
SettingsObject	200	Success.

Throws

Error Type	Error Message
BadRequestInvalidInput	Failed. The input is invalid.
Forbidden	Failed. Forbidden.
NotFoundObject	No object available for the given objectId.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsObjectsClient } from "@dynatrace-sdk/client-settings";

const data = await settingsObjectsClient.getSettingsObject({
  objectId: "...",
});

listEffectiveSettingsValues

settingsObjectsClient.listEffectiveSettingsValues(config): Promise<EffectiveSettingsValuesList>

Lists effective settings values

Required scope: settings:objects:read

Lists effective settings values for selected schema. If no object is persisted for a schema with "multiObject": false, the default value as defined in the schema will be returned.

Parameters

Name	Type	Description
config.addFields	string	A list of fields to be included in the response. The provided set of fields extends the default set. Specify the required top-level fields, separated by commas (for example, summary,origin). Supported fields: summary, searchSummary, schemaId, schemaVersion, origin, modificationInfo, value. Default fields: value.
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.optimisticLockingVersion	string	The version of the objects list for optimistic locking. You can use it to detect simultaneous modifications by different users. It's generated upon retrieval of the list of objects (GET requests). " If specified and modifications were made between retrieval and the request, the request will fail.
config.pageKey	string	The cursor for the next page of results. You can find it in the nextPageKey field of the previous response. The first page is always returned if you don't specify the page-key query parameter. When the page-key is set to obtain subsequent pages, you must omit all other query parameters except the optimistic-locking-version parameter.
config.pageSize	number	The amount of settings objects in a single response payload. The maximal allowed page size is 500. If not set, the response won't be paged.
config.schemaId	string	Schema ID to which the requested objects belong. Only considered on load of the first page, when the page-key isn't set.
config.scope	string	Scope to which the requested objects belong. Only considered on load of the first page, when the page-key isn't set.

Returns

Return type	Status code	Description
EffectiveSettingsValuesList	200	Success. Uses chunked encoding.

Even if a response returns a successful response code it's possible that the result is incomplete due to an internal error.

In this case an 'error' property with information about the problem is added. The caller may decide to work with the incomplete result or do a retry of the operation.|

Throws

Error Type	Error Message
BadRequestInvalidInput	Failed. The input is invalid.
NotFoundSchemaIsNotFound	Failed. The specified schema isn't found.
ListVersionMismatch	Paging data is outdated. The data has been modified since the initial request, query again from the first page to ensure a consistent result or rerun the same query without the optimistic locking version parameter to ignore.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsObjectsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsObjectsClient.listEffectiveSettingsValues();

listSettingsObjects

settingsObjectsClient.listSettingsObjects(config): Promise<SettingsObjectsList>

Lists persisted settings objects

Required scope: settings:objects:read

Lists persisted settings objects for selected schemas.

If nothing is persisted or if all persisted settings objects aren't accessible due to missing permissions, no items will be returned.

To query the effective values (including schema defaults) see getEffectiveSettingsValues.

Parameters

Name	Type	Description
config.addFields	string	A list of fields to be included in the response. The provided set of fields extends the default set. Specify the required top-level fields, separated by commas (for example, summary,value). Supported fields: objectId, version, summary, searchSummary, scope, schemaId, schemaVersion, modificationInfo, resourceContext, value, owner, externalId. Default fields: objectId, version.
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.filter	string	The filter parameter, as explained here. Filtering is supported on the following fields: objectId modificationInfo.createdBy modificationInfo.createdTime modificationInfo.lastModifiedBy modificationInfo.lastModifiedTime value with properties and sub-properties separated by dot (for example, value.owningApp = 'Notebooks') externalId owner.type owner.id If this parameter is omitted, all settings objects will be returned. The maximum nesting depth (via parentheses) is 5. The maximum expression length is 1024 characters. Note that only fields included to the response via add-fields can be used for filtering.
config.optimisticLockingVersion	string	The version of the objects list for optimistic locking. You can use it to detect simultaneous modifications by different users. It's generated upon retrieval of the list of objects (GET requests). " If specified and modifications were made between retrieval and the request, the request will fail.
config.pageKey	string	The cursor for the next page of results. You can find it in the nextPageKey field of the previous response. The first page is always returned if you don't specify the page-key query parameter. When the page-key is set to obtain subsequent pages, you must omit all other query parameters except the optimistic-locking-version parameter.
config.pageSize	number	The amount of settings objects in a single response payload. The maximal allowed page size is 500. If not set, the response won't be paged.
config.schemaId	string	Schema ID to which the requested objects belong. To load the first page, when the page-key isn't set, this parameter is required.
config.scope	string	Scope to which the requested objects belong. To load the first page, when the page-key isn't set, this parameter is required.
config.sort	string	The sort parameter, as explained here. Sorting is supported on the following fields: modificationInfo.createdBy modificationInfo.createdTime modificationInfo.lastModifiedBy modificationInfo.lastModifiedTime value with properties and sub-properties separated by dot (for example, value.owningApp) Note that only fields included to the response via add-fields can be used for sorting.

Returns

Return type	Status code	Description
SettingsObjectsList	200	Success. Uses chunked encoding.

Even if a response returns a successful response code it's possible that the result is incomplete due to an internal error.

In this case an 'error' property with information about the problem is added. The caller may decide to work with the incomplete result or do a retry of the operation.|

Throws

Error Type	Error Message
BadRequestInvalidInput	Failed. The input is invalid.
Forbidden	Failed. Forbidden.
NotFoundSchema	Failed. The specified schema wasn't found.
ListVersionMismatch	Paging data is outdated. The data has been modified since the initial request, query again from the first page to ensure a consistent result or rerun the same query without the optimistic locking version parameter to ignore.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsObjectsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsObjectsClient.listSettingsObjects();

reorderSettingsObjects

settingsObjectsClient.reorderSettingsObjects(config): Promise<ReorderResponse>

Reorder multi-object settings objects

Required scope: settings:objects:write

Reorders settings objects for schemas defined as multi-object and ordered.

The new order is defined by the list of object IDs in the request body. If any objects change in the meantime, the reorder will be rejected to prevent overwriting concurrent changes, even if the changed objects aren't part of the defined reorder sections.

Parameters

Name	Type	Description
config.body*required	ReorderRequest
config.optimisticLockingVersion*required	string	The version of the objects for optimistic locking. You can use it to detect simultaneous modifications by different users. It's generated upon retrieval of the list of objects (GET requests). The reorder will be allowed only if there wasn't any change between the retrieval and the update.

Returns

Return type	Status code	Description
ReorderResponse	200	Success.

Throws

Error Type	Error Message
BadRequestInvalidInput	Failed. The input is invalid.
Forbidden	Failed. Forbidden.
NotFoundResource	Failed. The requested resource doesn't exist.
ConflictingResource	Failed. Conflicting resource.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsObjectsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsObjectsClient.reorderSettingsObjects({
    optimisticLockingVersion: "...",
    body: {
      schemaId: "builtin:schema",
      scope: "environment",
      sections: [
        {
          firstObjectId: "...",
          lastObjectId: "...",
          order: [{ objectId: "..." }],
        },
      ],
    },
  });

updateSettingsObject

settingsObjectsClient.updateSettingsObject(config): Promise<void | SettingsUpdateResponse>

Updates an existing settings object

Required scope: settings:objects:write

Updates an existing settings object with new values. To update a property of the secret type you need to pass the new value unmasked. To keep the current value, send the current masked secret. You can obtain it via GET an object endpoint.

Some schemas don't allow passing of the masked secret. In that case you need to send the unmasked secret with every update of the object.

Parameters

Name	Type	Description
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.body*required	SettingsObjectUpdate
config.objectId*required	string	The ID of the required settings object
config.optimisticLockingVersion*required	string	The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It's 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.
config.validateOnly	boolean	If true, the request runs only validation of the submitted settings object, without saving it.

Returns

Return type	Status code	Description
SettingsUpdateResponse	200	Success.
void	204	Success. No validation errors.

Throws

Error Type	Error Message
BadRequestInvalidInput	Failed. The input is invalid.
Forbidden	Failed. Forbidden.
NotFoundResource	Failed. The requested resource doesn't exist.
ConflictingResource	Failed. Conflicting resource.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsObjectsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsObjectsClient.updateSettingsObject({
    objectId: "...",
    optimisticLockingVersion: "...",
    body: { value: {} },
  });

upsertSettingsObject

settingsObjectsClient.upsertSettingsObject(config): Promise<void | SettingsObjectResponse>

Creates a new settings object

Required scope: settings:objects:write

Parameters

Name	Type	Description
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.body*required	SettingsObjectCreate
config.validateOnly	boolean	If true, the request runs only validation of the submitted settings objects, without saving them.

Returns

Return type	Status code	Description
SettingsObjectResponse	200	Existing object successfully updated.
SettingsObjectResponse	201	Created.
void	204	Success. No validation errors.

Throws

Error Type	Error Message
BadRequestInvalidInput	Failed. The input is invalid.
Forbidden	Failed. Forbidden.
NotFoundResource	Failed. The requested resource doesn't exist.
ConflictingResource	Failed. Conflicting resource.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsObjectsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsObjectsClient.upsertSettingsObject({
    body: {
      schemaId: "jira-connection",
      scope: "environment",
      value: {},
    },
  });

settingsPermissionsClient

import { settingsPermissionsClient } from '@dynatrace-sdk/client-settings';

addSettingsObjectAccessorPermissions

settingsPermissionsClient.addSettingsObjectAccessorPermissions(config): Promise<AccessorPermissions>

Required scope: settings:objects:write

Add the permissions for a single accessor on this object, anyone with read/write permissions is allowed to add more permissions

Parameters

Name	Type	Description
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.body*required	AccessorPermissions
config.objectId*required	string	The ID of the required settings object

Returns

Return type	Status code	Description
AccessorPermissions	201	Success.

Throws

Error Type	Error Message
BadRequestAccessorIdAlreadyExists	If accessor id already exists.
NotFoundObject	No object available for the given objectId.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsPermissionsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsPermissionsClient.addSettingsObjectAccessorPermissions(
    {
      objectId: "...",
      body: { accessor: { type: "user" }, permissions: {} },
    },
  );

deleteSettingsObjectAccessorPermissions

settingsPermissionsClient.deleteSettingsObjectAccessorPermissions(config): Promise<void>

Required scope: settings:objects:write

Remove the permissions for an existing accessor on this object, anyone with read/write permissions is allowed to delete permissions

Parameters

Name	Type	Description
config.accessorId*required	string	The user uuid or group uuid of the accessor, depending on the type
config.accessorType*required	"user" | "group"	The type of the accessor
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.objectId*required	string	The ID of the required settings object

Returns

Return type	Status code	Description
void	204	Success.

Throws

Error Type	Error Message
NotFoundObjectOrNoPermissions	No object available for the given objectId or the accessor doesn't have any permissions on this object.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsPermissionsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsPermissionsClient.deleteSettingsObjectAccessorPermissions(
    {
      objectId: "...",
      accessorType: "user",
      accessorId: "...",
    },
  );

deleteSettingsObjectAllUsersPermissions

settingsPermissionsClient.deleteSettingsObjectAllUsersPermissions(config): Promise<void>

Required scope: settings:objects:write

Remove the permissions for an existing all-users accessor on this object, anyone with read/write permissions is allowed to delete permissions

Parameters

Name	Type	Description
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.objectId*required	string	The ID of the required settings object

Returns

Return type	Status code	Description
void	204	Success.

Throws

Error Type	Error Message
NotFoundObjectOrAllUsersNoPermissions	No object available for the given objectId or the all-users accessor doesn't have any permissions on this object.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsPermissionsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsPermissionsClient.deleteSettingsObjectAllUsersPermissions(
    { objectId: "..." },
  );

getSettingsObjectAccessorPermissions

settingsPermissionsClient.getSettingsObjectAccessorPermissions(config): Promise<AccessorPermissions>

Required scope: settings:objects:read

Get current permissions of the accessor on this object

Parameters

Name	Type	Description
config.accessorId*required	string	The user uuid or group uuid of the accessor, depending on the type
config.accessorType*required	"user" | "group"	The type of the accessor
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.objectId*required	string	The ID of the required settings object

Returns

Return type	Status code	Description
AccessorPermissions	200	Success.

Throws

Error Type	Error Message
NotFoundObjectOrNoPermissions	No object available for the given objectId or the accessor doesn't have any permissions on this object.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsPermissionsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsPermissionsClient.getSettingsObjectAccessorPermissions(
    {
      objectId: "...",
      accessorType: "user",
      accessorId: "...",
    },
  );

getSettingsObjectAllUsersPermissions

settingsPermissionsClient.getSettingsObjectAllUsersPermissions(config): Promise<AccessorPermissions>

Required scope: settings:objects:read

Get current permissions of the all-users accessor on this object

Parameters

Name	Type	Description
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.objectId*required	string	The ID of the required settings object

Returns

Return type	Status code	Description
AccessorPermissions	200	Success.

Throws

Error Type	Error Message
NotFoundObjectOrAllUsersNoPermissions	No object available for the given objectId or the all-users accessor doesn't have any permissions on this object.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsPermissionsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsPermissionsClient.getSettingsObjectAllUsersPermissions(
    { objectId: "..." },
  );

getSettingsObjectPermissions

settingsPermissionsClient.getSettingsObjectPermissions(config): Promise<AccessorPermissionsList>

Required scope: settings:objects:read

Get current permissions on this object

Parameters

Name	Type	Description
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.objectId*required	string	The ID of the required settings object

Returns

Return type	Status code	Description
AccessorPermissionsList	200	Success.

Throws

Error Type	Error Message
NotFoundObject	No object available for the given objectId.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsPermissionsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsPermissionsClient.getSettingsObjectPermissions(
    { objectId: "..." },
  );

resolveEffectivePermissions

settingsPermissionsClient.resolveEffectivePermissions(config): Promise<EffectivePermissions>

Get the effective settings permissions of the calling user in the environment

Required scope: settings:schemas:read

Parameters

Name	Type
config.body*required	ResolutionRequest

Throws

Error Type	Error Message
BadRequestInvalidInput	Failed. The input is invalid.
ForbiddenNoSchemaAccess	Failed. Forbidden. No access to any schema.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsPermissionsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsPermissionsClient.resolveEffectivePermissions(
    {
      body: {
        permissions: [
          {
            permission: "settings:objects:read",
            context: { schemaId: "...", scope: "..." },
          },
        ],
      },
    },
  );

transferSettingsObjectOwnership

settingsPermissionsClient.transferSettingsObjectOwnership(config): Promise<void>

Required scope: settings:objects:write

Change owner of the object, only the owner or the main admin is allowed to transfer the ownership (IAM permission needed).

Parameters

Name	Type	Description
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.body*required	TransferOwnershipRequest
config.objectId*required	string	The ID of the required settings object

Returns

Return type	Status code	Description
void	204	Success.

Throws

Error Type	Error Message
NotFoundObject	No object available for the given objectId.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsPermissionsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsPermissionsClient.transferSettingsObjectOwnership(
    {
      objectId: "...",
      body: { newOwner: { type: "user" } },
    },
  );

updateSettingsObjectAccessorPermissions

settingsPermissionsClient.updateSettingsObjectAccessorPermissions(config): Promise<void>

Required scope: settings:objects:write

Update the permissions for an existing accessor on this object, anyone with read/write permissions is allowed to update permissions

Parameters

Name	Type	Description
config.accessorId*required	string	The user uuid or group uuid of the accessor, depending on the type
config.accessorType*required	"user" | "group"	The type of the accessor
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.body*required	UpdatePermissionsRequest
config.objectId*required	string	The ID of the required settings object

Returns

Return type	Status code	Description
void	200	Success.

Throws

Error Type	Error Message
BadRequestPermissionListInvalid	If permission list is empty, contains unsupported entries or unsupported combinations of entries.
NotFoundObjectOrNoPermissions	No object available for the given objectId or the accessor doesn't have any permissions on this object.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsPermissionsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsPermissionsClient.updateSettingsObjectAccessorPermissions(
    {
      objectId: "...",
      accessorType: "user",
      accessorId: "...",
      body: { permissions: {} },
    },
  );

updateSettingsObjectAllUsersPermissions

settingsPermissionsClient.updateSettingsObjectAllUsersPermissions(config): Promise<void>

Required scope: settings:objects:write

Update the permissions for an existing all-users accessor on this object, anyone with read/write permissions is allowed to update permissions

Parameters

Name	Type	Description
config.adminAccess	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects
config.body*required	UpdatePermissionsRequest
config.objectId*required	string	The ID of the required settings object

Returns

Return type	Status code	Description
void	200	Success.

Throws

Error Type	Error Message
BadRequestPermissionListInvalid	If permission list is empty, contains unsupported entries or unsupported combinations of entries.
NotFoundObjectOrAllUsersNoPermissions	No object available for the given objectId or the all-users accessor doesn't have any permissions on this object.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsPermissionsClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsPermissionsClient.updateSettingsObjectAllUsersPermissions(
    { objectId: "...", body: { permissions: {} } },
  );

settingsSchemasClient

import { settingsSchemasClient } from '@dynatrace-sdk/client-settings';

getSchemaDefinition

settingsSchemasClient.getSchemaDefinition(config): Promise<SettingsSchemaDefinition>

Gets parameters of the specified settings schema.

Required scope: settings:schemas:read

Gets parameters of the specified settings schema.

Parameters

Name	Type	Description
config.schemaId*required	string	The ID of the required schema.
config.schemaVersion	string	The version of the required schema. If not set, the most recent version is returned.

Returns

Return type	Status code	Description
SettingsSchemaDefinition	200	Success.

Throws

Error Type	Error Message
NotFoundSchemaDoesNotExist	Failed. The specified schema doesn't exist.
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsSchemasClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsSchemasClient.getSchemaDefinition({
    schemaId: "...",
  });

listSchemaDefinitions

settingsSchemasClient.listSchemaDefinitions(config): Promise<SchemaList>

Lists available settings schemas.

Required scope: settings:schemas:read

Lists available settings schemas.

Parameters

Name	Type	Description
config.addFields	string	A list of fields to be included in the response. The provided set of fields extends the default set. Specify the required top-level fields, separated by commas (for example, multiObject,ordered). Supported fields: schemaId, displayName, latestSchemaVersion, maturity, multiObject, ordered, ownerBasedAccessControl, schemaVersions. Default fields: schemaId, displayName, latestSchemaVersion.

Returns

Return type	Status code	Description
SchemaList	200	Success.

Throws

Error Type	Error Message
TooManyRequests	Failed. Too many requests.
ServiceUnavailable	Failed. Service unavailable.
GeneralError	Error.

Code example

import { settingsSchemasClient } from "@dynatrace-sdk/client-settings";

const data =
  await settingsSchemasClient.listSchemaDefinitions();

Types

AccessorPermissions

Name	Type
accessor*required	Identity
permissions*required	PermissionsList

AccessorPermissionsList

Name	Type
accessors*required	Array<AccessorPermissions>

BiComparableContainerConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
properties*required	Array<string>	For type in [GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL] exactly two properties are required.
type*required	"GREATER_THAN" | "GREATER_THAN_OR_EQUAL" | "LESS_THAN" | "LESS_THAN_OR_EQUAL"	Type also defines which properties are available.

ByteSizeLimitConstraint

Name	Type	Description
byteLimit*required	number	For type = BYTE_SIZE_LIMIT
customMessage	string	Message to be displayed if constraint is violated.
type*required	"BYTE_SIZE_LIMIT"	Type also defines which properties are available.

ComplexType

Name	Type	Description
constraints	Array<ContainerConstraint>	Container validation constraints the type values must fulfill to be persistable.
description	string	Short description of what this type is used for. default: ""
displayName	string	Defaults to id in the code-api.
documentation	string	Additional information about the type, explanation of semantics of its values.
properties*required	ComplexTypeProperties	Order is relevant for UI, not for serialization.
searchPattern	string	If not specified the summaryPattern is used for search.
summaryPattern	string	Defaults to empty string. Markdown symbols need to be escaped if they're to be displayed normally. default: ""
type*required	"object"	Always has to be object for complex types. default: "object"
version	string	Semantic version x.y.z, defaults to 0, has to be increased when properties are added/removed or structurally modified (type, nullable). default: "0" Pattern: ^\d+(\.\d+)*$
versionInfo	string	Defaults to empty string. default: ""

ComplexTypeProperties

Order is relevant for UI, not for serialization.

type: Record<string, Property>

ConstraintViolation

Contains information about a constraint violation caused by invalid input.

Name	Type	Description
message*required	string	The constraint violation description message
parameterLocation	"PATH" | "QUERY" | "HEADER" | "PAYLOAD_BODY"	Describes the general location of the violating parameter
path	string	The path of the parameter that caused the constraint violation

CustomContainerValidationRequest

The request payload for a custom validation of a container.

Name	Type	Description
key	string	The key of the setting being validated.
path	string	The path of the container being validated.
value*required	CustomContainerValidationRequestValue	The container value.

CustomContainerValidationRequestValue

The container value.

type: Record<string, any>

CustomDeletionValidatorReferenceConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
customValidatorId*required	string	For type = CUSTOM_VALIDATOR_REF
type	"CUSTOM_VALIDATOR_REF"	Type also defines which properties are available.

CustomPropertyValidationRequest

The request payload for a custom validation of a single property value.

Name	Type	Description
arrayValue	null | Array<any>	The property value.
booleanValue	null | boolean	The property value.
floatValue	null | number	The property value.
intValue	null | number	The property value.
path	string	The path of the property being validated.
stringValue	string	The property value.

CustomSchemaValidatorReferenceConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
customValidatorId*required	string	For type = CUSTOM_VALIDATOR_REF or MULTI_SCOPE_CUSTOM_VALIDATOR_REF.
skipAsyncValidation	boolean	false - validate on every change in the UI, true - validate only on save default: false
type*required	"CUSTOM_VALIDATOR_REF" | "MULTI_SCOPE_CUSTOM_VALIDATOR_REF"	Type also defines which properties are available.

CustomValidatorReferenceConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
customValidatorId*required	string	For type = CUSTOM_VALIDATOR_REF.
skipAsyncValidation	boolean	false - validate on every change in the UI, true - validate only on save default: false
timeout	number	For type = CUSTOM_VALIDATOR_REF. Default is 5 s. default: 5
type*required	"CUSTOM_VALIDATOR_REF"	Type also defines which properties are available.

CustomValidatorReferenceContainerConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
customValidatorId*required	string	For type = CUSTOM_VALIDATOR_REF.
skipAsyncValidation	boolean	false - validate on every change in the UI, true - validate only on save default: false
timeout	number	For type = CUSTOM_VALIDATOR_REF. Default is 5 s. default: 5
type*required	"CUSTOM_VALIDATOR_REF"	Type also defines which properties are available.

Datasource

Name	Type	Description
filterProperties	Array<string>
fullContext	boolean	default: false
identifier*required	string
resetValue	"ALWAYS" | "NEVER" | "INVALID_ONLY"	Hint to the UI to reset value when one of the filter properties changed default: "NEVER"
useApiSearch	boolean	This should be used for datasources that have scaling amounts of options, or exceptionally many. default: false
validate	boolean	default: true

EffectivePermission

Name	Type
context	PermissionContext
granted*required	"true" | "false" | "condition"
permission*required	string

EffectivePermissions

type: Array<EffectivePermission>

EffectiveSettingsValue

An effective settings value.

Name	Type	Description
classicOrigin	string	The origin of the settings value in a classic format. Either a scope or default.
modificationInfo	ModificationInfo	Modification information about the setting.
origin	string	The origin of the settings value. Either a scope or default.
schemaId	string	The schema on which the object is based.
schemaVersion	string	The version of the schema on which the object is based.
searchSummary	string	A searchable summary string of the setting value. Plain text without Markdown.
summary	string	A short summary of settings. This can contain Markdown and will be escaped accordingly.
value	SettingsValue	The value of the setting. It defines the actual values of settings' parameters. The actual content depends on the object's schema.

EffectiveSettingsValuesList

A list of effective settings values.

Name	Type	Description
error	ErrorIncomplete	Error object for an incomplete response
items*required	Array<EffectiveSettingsValue>	A list of effective settings values.
nextPageKey	string	The cursor for the next page of results. Has the value of null on the last page. Use it in the page-key query parameter to obtain subsequent pages of the result.
pageSize*required	number	The number of entries per page.
totalCount*required	number	The total number of entries in the result.
version*required	string	The version of the settings objects list for optimistic locking." You can use it to detect simultaneous modifications by different users. It's generated upon retrieval (GET requests). If set on a followup GET request, it fails if there was a change between these two requests.

EnumType

Name	Type	Description
checkForDuplicateDisplayNames	boolean	Should only be set for enums that are used in combination with a datasource (so that no duplicates are ever displayed). default: true
description	string	Short description of what this type is used for. default: ""
displayName	string	Defaults to id in the code-api.
documentation	string	Additional information about the type, explanation of semantics of its values. default: ""
enumClass	string	Fully-qualified name of the java enum class this enum should be mapped to.
items*required	Array<EnumValue>	Mapping from enum values to displayName.
type*required	"enum"	Always has to be enum for enum types. default: "enum"

EnumValue

Name	Type	Description
description	string	The human-friendly optional description of the value.
displayName*required	string	The human-friendly name of the value.
enumInstance	string	Reference to an instance of #EnumType/enumClass using Enum::name
icon	string	An optional barista icon that's displayed next to the value.
value*required	string	Persisted value for the enum item

EqualsPrecondition

Name	Type	Description
expectedValue*required	string | number | boolean | Date	For type = EQUALS, type of value should match type of referenced property.
property*required	string	For type in [NULL, EQUALS, IN, REGEX_MATCH].
type*required	"EQUALS"	Type also defines which properties are required.

Error

Standard error response

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

ErrorDetails

Optional details of the error

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

ErrorIncomplete

Error object for an incomplete response

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

ErrorResponse

Name	Type	Description
error*required	Error	Standard error response

Identity

Name	Type	Description
id	string	user id or user group id if type is 'user' or 'group', missing if type is 'all-users'
type*required	"user" | "group" | "all-users"

InPrecondition

Name	Type	Description
expectedValues*required	Array<string | number | boolean | Date>	For type = IN, type of values should match type of referenced property.
property*required	string	For type in [NULL, EQUALS, IN, REGEX_MATCH].
type*required	"IN"	Type also defines which properties are required.

Item

Name	Type	Description
constraints	Array<Constraint>	Validation constraints the list/set item value must fulfill to be persistable.
datasource	Datasource
description	string	Short description of what this list/set item is used for.
displayName	string	The human-friendly name of the list/set item.
documentation	string	Additional information about the list/set item, explanation of semantics of its values.
metadata	MetaData
referencedType	string	Mandatory for setting type, otherwise only optionally used in conjunction with subType.
subType	string	Only in combination with built-in and enum types.
type*required	string | RefPointer	Ref-pointer to ComplexType/EnumType id or enum boolean,integer,float,local_date,local_time,local_date_time,zoned_date_time,time_zone,text,secret,setting

JsonPatch

type: Record<string, Record<string, any>>

LengthConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
maxLength	number	For type = LENGTH and string values.
minLength	number	For type = LENGTH and string values.
type*required	"LENGTH"	Type also defines which properties are available.

MetaData

type: Record<string, string>

ModificationInfo

Modification information about the setting.

Name	Type	Description
createdBy	string	The unique identifier of the user who created the setting.
createdTime	Date	Timestamp when the setting was created in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')
lastModifiedBy	string	The unique identifier of the user who performed the most recent modification.
lastModifiedReason	string	The reason for the most recent modification, if available.
lastModifiedTime	Date	Timestamp when the setting was last modified in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

Modifications

The additional modification details for this settings object.

Name	Type	Description
first	boolean	If non-moveable settings object is in the first group of non-moveable settings, or in the last (start or end of list).
modifiablePaths*required	Array<string>	Property paths which are modifiable, regardless if the write operation is allowed.
movable	boolean	If settings object can be moved/reordered. Only applicable for ordered list schema.
nonModifiablePaths*required	Array<string>	Property paths which aren't modifiable, even if the write operation is allowed.

NoWhitespaceConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
type*required	"NO_WHITESPACE"	Type also defines which properties are available.

NotBlankConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
type*required	"NOT_BLANK"	Type also defines which properties are available.

NotEmptyConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
type*required	"NOT_EMPTY"	Type also defines which properties are available.

NotPrecondition

Name	Type	Description
precondition*required	Precondition
type*required	"NOT"	Type also defines which properties are required.

NullPrecondition

Name	Type	Description
property*required	string	For type in [NULL, EQUALS, IN, REGEX_MATCH].
type*required	"NULL"	Type also defines which properties are required.

PatternConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
pattern*required	string	For type = PATTERN and string values.
type*required	"PATTERN"	Type also defines which properties are available.

PermissionContext

Name	Type
schemaId*required	string
scope*required	string

PermissionsList

type: Array<"r" | "w">

Property

Name	Type	Description
constraints	Array<UniquePropertiesConstraint | Constraint>	Validation constraints the property value must fulfill to be persistable.
datasource	Datasource
default	string | number | boolean | Array<any> | Date | Record<string | any>	Mandatory if nullable = false, can't be set if nullable = true. Can't be empty for enum properties.
description	string	Short description of what this property is used for. default: ""
displayName*required	string	Defaults to id in the code-api.
documentation	string	Additional information about the property, explanation of semantics of its values. default: ""
forceSecretResubmission	boolean	If true any change to the property value also requires all properties of type secret to be provided default: false
items	Item
maxObjects	number	Defaults to 100 for collections and 1 for non-collections. default: 1
metadata	MetaData
migrationPattern	string
minObjects	number	Optional.
modificationPolicy	"ALWAYS" | "NEVER" | "DEFAULT"	DEFAULT - modifiability of the value is defined by ModificationFlags.isModifiable, ALWAYS/NEVER - the value can be always/never modified. Defaults to DEFAULT. Can't be used on properties inside a collection property. default: "DEFAULT"
nullable	boolean	Defaults to false. Can't be true for properties with type list and set. default: false
precondition	Precondition
referencedType	string	Mandatory for setting type, otherwise only optionally used in conjunction with subType.
subType	string	Only in combination with built-in types.
type*required	string | RefPointer	Ref-pointer to ComplexType/EnumType id or enum list,set,boolean,integer,float,local_date,local_time,local_date_time,zoned_date_time,time_zone,text,secret,setting.

PropertyCountRangeContainerConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
maximumPropertyCount	number	For type = PROPERTY_COUNT_RANGE.
minimumPropertyCount	number	For type = PROPERTY_COUNT_RANGE.
properties*required	Array<string>	For type in [for type = PROPERTY_COUNT_RANGE an arbitrary number of properties can be given.
type*required	"PROPERTY_COUNT_RANGE"	Type also defines which properties are available.

RangeConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
maximum	number	For type = RANGE and integer and floating-point numeric values.
minimum	number	For type = RANGE and integer and floating-point numeric values.
type*required	"RANGE"	Type also defines which properties are available.

RecursivePrecondition

Name	Type	Description
preconditions*required	Array<Precondition>	For type in [AND, OR].
type*required	"AND" | "OR"	Type also defines which properties are required.

RefPointer

Name	Type
$ref*required	string

ReferentialIntegrityDeletionConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
schemaIds*required	Array<string>	For type = REFERENTIAL_INTEGRITY
type*required	"REFERENTIAL_INTEGRITY"	Type also defines which properties are available.

RegexConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
disallowDangerousRegex	boolean	true - regex must be safe, false - unsafe regexes are allowed default: false
type*required	"REGEX"	Type also defines which properties are available.

RegexMatchPrecondition

Name	Type	Description
pattern*required	string	For type = REGEX_MATCH, type of value should be string.
property*required	string	For type in [NULL, EQUALS, IN, REGEX_MATCH].
type*required	"REGEX_MATCH"	Type also defines which properties are required.

ReorderObject

Name	Type	Description
objectId*required	string	The objectId of the settings object.

ReorderRequest

Name	Type	Description
schemaId*required	string	The schema to which the objects belong.
scope*required	string	The scope to which the objects belong.
sections*required	Array<ReorderSection>	Defines the reorder operations. Each section defines a contiguous range of objects in the source list that should be reordered. The sections must not overlap. Moving an object from one section to another isn't possible.

ReorderResponse

Name	Type	Description
items*required	Array<ReorderResponseItemsItem>	A list of settings objects after reordering. Only contains the objects that were part of the request.
version*required	string	The version of the settings objects list for optimistic locking.

ReorderResponseItemsItem

Name	Type	Description
objectId*required	string	The ID of the settings object.
version*required	string	The version of the object for optimistic locking.

ReorderSection

Name	Type	Description
firstObjectId*required	string	The objectId of the first object of the source list that should be included in this section.
lastObjectId*required	string	The objectId of the last object of the source list that should be included in this section.
order*required	Array<ReorderObject>	The new order of objects spanning all objects between firstObject and lastObject inclusive.

ResolutionRequest

Name	Type
permissions*required	Array<SinglePermissionRequest>

ResourceContext

The resource context, which contains additional permission information about the object.

Name	Type	Description
modifications*required	Modifications	The additional modification details for this settings object.
operations*required	Array<"read" | "write" | "delete">	The allowed operations on this settings object.

RevisionDiff

The diff between two revisions.

Name	Type	Description
appId	string	The id of the app which changed the settings object.
jsonAfter	string	The new value of the changed settings value or null if the value has been deleted.
jsonBefore	string	The previous value of the changed settings value or null if the value has been newly created.
jsonPatch	null | Array<JsonPatch>	The JSON Patch for this value. May be null if the diff type isn't UPDATE.
modificationInfo*required	ModificationInfo	Modification information about the setting.
objectId	string	The ID of the settings object.
ownerAfter	Identity
ownerBefore	Identity
revision*required	string	The revision of the change.
schemaDisplayName	string	The display name of the schema to which the revision belongs.
schemaId	string	Schema ID to which the revision belongs.
schemaVersion	string	The schema version the new value complies to.
source	string	The source of the change.
summary	string	Summary of the object value corresponding to the summary pattern of the schema.
type	"CREATE" | "DELETE" | "NO_CHANGE" | "REORDER" | "UPDATE"	The type of the difference.

RevisionDiffPage

The paged response payload for diff between revisions of settings.

Name	Type	Description
endTime	string	The 'to' time in ISO Date Time Format from the original request.
items	Array<RevisionDiff>	The list of revisions changes in the current page.
nextPageKey	string	The cursor for the next page of results. Has the value of null on the last page. Use it in the page-key query parameter to obtain subsequent pages of the result.
pageSize	number	The number of entries per page.
startTime	string	The 'from' time in ISO Date Time Format from the original request.
totalCount*required	number	The total number of entries in the result.

SchemaList

The list of available settings schemas.

Name	Type	Description
items*required	Array<SchemaStub>	A list of settings schemas.
totalCount*required	number	The number of schemas in the list.

SchemaStub

The short representation of the settings schema.

Name	Type	Description
displayName*required	string	The name of the schema.
latestSchemaVersion*required	string	The most recent version of the schema.
maturity	"PREVIEW" | "EARLY_ADOPTER" | "GENERAL_AVAILABILITY"	The maturity of the schema.
multiObject	boolean	Multi-object flag. True if the schema is a multi-object schema
ordered	boolean	Ordered flag. True if the schema is an ordered multi-object schema.
ownerBasedAccessControl	boolean	Owner based access control flag. True if the schema has owner based access control enabled.
schemaId*required	string	The ID of the schema.
schemaVersions	Array<string>	A list of available (GA) versions of the schema.

SecretResubmissionContainerConstraint

Name	Type	Description
checkAllProperties*required	boolean	Either all properties or only those marked with forceSecretResubmission are considered.
customMessage	string	Message to be displayed if constraint is violated.
type*required	"SECRET_RESUBMISSION"	Type also defines which properties are available.

SettingsDefaultObject

The default settings object for the given schema.

Name	Type	Description
searchSummary	string	A searchable summary string of the object. Plain text without Markdown. Only set if the schema is a multi-object schema.
summary	string	A short summary of the object. Only set if the schema is a multi-object schema.
value*required	SettingsValue	The value of the setting. It defines the actual values of settings' parameters. The actual content depends on the object's schema.

SettingsObject

A settings object.

Name	Type	Description
classicScope	string	The classic scope that the object targets. For more details, see Dynatrace Documentation.
externalId	string	The externalId of the object.
modificationInfo	ModificationInfo	Modification information about the setting.
objectId*required	string	The ID of the settings object.
owner	Identity
resourceContext	ResourceContext	The resource context, which contains additional permission information about the object.
schemaId	string	The schema on which the object is based.
schemaVersion	string	The version of the schema on which the object is based.
scope	string	The scope that the object targets. For more details, see Dynatrace Documentation.
searchSummary	string	A searchable summary string of the setting value. Plain text without Markdown.
summary	string	A short summary of settings. This can contain Markdown and will be escaped accordingly.
value	SettingsValue	The value of the setting. It defines the actual values of settings' parameters. The actual content depends on the object's schema.
version*required	string	The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It's 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.

SettingsObjectCreate

Configuration of a new settings object.

Name	Type	Description
externalId	string	External id for upserts.
insertNeighbor	string	The position of the new object based on the objectId of the neighbor. Only for insertPosition afterand before
insertPosition	"first" | "last" | "after" | "before"
schemaId*required	string	The schema on which the object is based.
schemaVersion	string	The version of the schema on which the object is based.
scope*required	string	The scope of the settings object.
value*required	SettingsValue	The value of the setting. It defines the actual values of settings' parameters. The actual content depends on the object's schema.

SettingsObjectResponse

The response to a creation request. Only contains the ID and version, not the full object.

Name	Type	Description
objectId*required	string	The ID of the created settings object.
version*required	string	The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It's 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.

SettingsObjectSummarize

The settings object to summarize.

Name	Type	Description
schemaVersion	string	The version of the schema on which the object is based.
value*required	SettingsValue	The value of the setting. It defines the actual values of settings' parameters. The actual content depends on the object's schema.

SettingsObjectSummary

The summary of the provided settings object according to the schema.

Name	Type	Description
items	null | Array<SettingsObjectSummary>	The summaries of the items in this property (if this property is a collection).
properties	SettingsObjectSummaryProperties	The summaries of the child properties by their name.
searchSummary*required	string	A searchable summary string of the setting value. Plain text without Markdown.
summary*required	string	A short summary of the settings object. This can contain Markdown and will be escaped accordingly.

SettingsObjectSummaryProperties

The summaries of the child properties by their name.

type: Record<string, SettingsObjectSummary>

SettingsObjectUpdate

An update of a settings object.

Name	Type	Description
externalId	string	External identifier for the object being updated
insertNeighbor	string	The position of the new object based on the objectId of the neighbor. Only for insertPosition afterand before
insertPosition	"first" | "last" | "after" | "before"
schemaVersion	string	The version of the schema on which the object is based.
value*required	SettingsValue	The value of the setting. It defines the actual values of settings' parameters. The actual content depends on the object's schema.

SettingsObjectsList

A list of settings objects.

Name	Type	Description
error	ErrorIncomplete	Error object for an incomplete response
items*required	Array<SettingsObject>	A list of settings objects.
nextPageKey	string	The cursor for the next page of results. Has the value of null on the last page. Use it in the page-key query parameter to obtain subsequent pages of the result.
pageSize*required	number	The number of entries per page.
totalCount*required	number	The total number of entries in the result.
version*required	string	The version of the settings objects list for optimistic locking." You can use it to detect simultaneous modifications by different users. It's generated upon retrieval (GET requests). If set on reorder, the update will be allowed only if there wasn't any change between the retrieval and the update. If set on a followup GET request, it fails if there was a change between these two requests.

SettingsSchemaDefinition

Name	Type	Description
allowedScopes*required	Array<string>	A list of scopes where the schema can be used.
constraints	Array<ContainerConstraint | SecretResubmissionContainerConstraint>	A list of constrains limiting the values to be accepted by the schema.
deletionConstraints	Array<CustomDeletionValidatorReferenceConstraint | ReferentialIntegrityDeletionConstraint>	Constraints limiting the values to be deleted.
description*required	string	A short description of the schema.
displayName*required	string	The display name of the schema.
documentation	string	An extended description of the schema and/or links to documentation.
dynatrace*required	string	The version of the data format.
enums*required	SettingsSchemaDefinitionEnums	A list of definitions of enum properties.
keyProperty	string	Name of the key property in this schema.
maturity	"PREVIEW" | "EARLY_ADOPTER" | "GENERAL_AVAILABILITY"	The maturity of the schema. Possible values: PREVIEW: Preview features aren't generally available, but might be available in specific environments as part of early-access programs. These are the most likely to change in incompatible ways. EARLY_ADOPTER: Features marked "early adopter" are available in all environments, but aren't mature enough to warrant the "general availability" designation. We don't expect incompatible changes for these, but be aware, that these aren't fully stable yet and incompatible changes may be necessary in rare cases. GENERAL_AVAILABILITY: Features marked "general availability" are the most stable. While the schemas will still evolve over time, care will be taken to only do so in a backward-compatible manner. In any case, automations should make use of the schemaVersion field when writing settings objects.
maxObjects*required	number	The maximum amount of objects per scope. Only applicable when multiObject is set to true.
metadata	SettingsSchemaDefinitionMetadata	Metadata of the setting.
multiObject*required	boolean	Multiple (true) objects per scope are permitted or a single (false) object per scope is permitted.
ordered	boolean	If true the order of objects has semantic significance. Only applicable when multiObject is set to true.
properties*required	SettingsSchemaDefinitionProperties	A list of schema's properties.
schemaConstraints	Array<SchemaConstraint>	Constraints limiting the values as a whole to be accepted in this configuration element.
schemaGroups	Array<string>	Names of the groups, which the schema belongs to.
schemaId*required	string	The ID of the schema.
types*required	SettingsSchemaDefinitionTypes	A list of definitions of types. A type is a complex property that contains its own set of subproperties.
version*required	string	The version of the schema.

SettingsSchemaDefinitionEnums

A list of definitions of enum properties.

type: Record<string, EnumType>

SettingsSchemaDefinitionMetadata

Metadata of the setting.

type: Record<string, string>

SettingsSchemaDefinitionProperties

A list of schema's properties.

type: Record<string, Property>

SettingsSchemaDefinitionTypes

A list of definitions of types.

A type is a complex property that contains its own set of subproperties.

type: Record<string, ComplexType>

SettingsUpdateResponse

The response to an update request.

Name	Type	Description
version*required	string	The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users. It's 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.

SettingsValue

The value of the setting.

It defines the actual values of settings' parameters.

The actual content depends on the object's schema.

type: Record<string, any>

SinglePermissionRequest

optional generic set of context data

Name	Type
context	PermissionContext
permission*required	"settings:objects:read" | "settings:objects:write" | "settings:objects:admin"

TransferOwnershipRequest

Name	Type
newOwner*required	Identity

TrimmedConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
type*required	"TRIMMED"	Type also defines which properties are available.

UniqueMultiScopeSchemaPropertiesConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
type*required	"MULTI_SCOPE_UNIQUE"	Type also defines which properties are available.
uniqueProperties*required	Array<string>	For type = MULTI_SCOPE_UNIQUE

UniquePropertiesConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
type*required	"UNIQUE"	Type also defines which properties are available.
uniqueProperties*required	Array<string>	For type = UNIQUE.

UniqueSchemaPropertiesConstraint

Name	Type	Description
customMessage	string	Message to be displayed if constraint is violated.
flattenCollections	boolean	For type = UNIQUE default: false
type*required	"UNIQUE"	Type also defines which properties are available.
uniqueProperties*required	Array<string>	For type = UNIQUE

UpdatePermissionsRequest

Name	Type
permissions*required	PermissionsList

ValidationResponse

Name	Type
constraintViolations	Array<ViolationResponse>
message	string
valid*required	boolean

ViolationResponse

Name	Type
message	string
path	string

Constraint

type: LengthConstraint | RangeConstraint | NotBlankConstraint | NotEmptyConstraint | TrimmedConstraint | NoWhitespaceConstraint | RegexConstraint | PatternConstraint | CustomValidatorReferenceConstraint

ContainerConstraint

type: BiComparableContainerConstraint | CustomValidatorReferenceContainerConstraint | PropertyCountRangeContainerConstraint

Precondition

type: RecursivePrecondition | NotPrecondition | EqualsPrecondition | InPrecondition | NullPrecondition | RegexMatchPrecondition

SchemaConstraint

type: UniqueSchemaPropertiesConstraint | UniqueMultiScopeSchemaPropertiesConstraint | CustomSchemaValidatorReferenceConstraint | ByteSizeLimitConstraint

Enums

BiComparableContainerConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

GreaterThan | GreaterThanOrEqual | LessThan | LessThanOrEqual

ByteSizeLimitConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

ByteSizeLimit

ComplexTypeType

⚠️ Deprecated Use literal values.

Always has to be object for complex types.

Enum keys

Object

ConstraintViolationParameterLocation

⚠️ Deprecated Use literal values.

Describes the general location of the violating parameter

Enum keys

Header | Path | PayloadBody | Query

CustomDeletionValidatorReferenceConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

CustomValidatorRef

CustomSchemaValidatorReferenceConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

CustomValidatorRef | MultiScopeCustomValidatorRef

CustomValidatorReferenceConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

CustomValidatorRef

CustomValidatorReferenceContainerConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

CustomValidatorRef

DatasourceResetValue

⚠️ Deprecated Use literal values.

Hint to the UI to reset value when one of the filter properties changed

Enum keys

Always | InvalidOnly | Never

EffectivePermissionGranted

⚠️ Deprecated Use literal values.

Enum keys

Condition | False | True

EnumTypeType

⚠️ Deprecated Use literal values.

Always has to be enum for enum types.

Enum keys

Enum

EqualsPreconditionType

⚠️ Deprecated Use literal values.

Type also defines which properties are required.

Enum keys

Equals

GetSettingsObjectAccessorPermissionsPathAccessorType

⚠️ Deprecated Use literal values.

Enum keys

Group | User

IdentityType

⚠️ Deprecated Use literal values.

Enum keys

AllUsers | Group | User

InPreconditionType

⚠️ Deprecated Use literal values.

Type also defines which properties are required.

Enum keys

In

LengthConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

Length

NoWhitespaceConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

NoWhitespace

NotBlankConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

NotBlank

NotEmptyConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

NotEmpty

NotPreconditionType

⚠️ Deprecated Use literal values.

Type also defines which properties are required.

Enum keys

Not

NullPreconditionType

⚠️ Deprecated Use literal values.

Type also defines which properties are required.

Enum keys

Null

PatternConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

Pattern

PermissionsListItem

⚠️ Deprecated Use literal values.

Enum keys

R | W

PropertyCountRangeContainerConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

PropertyCountRange

PropertyModificationPolicy

⚠️ Deprecated Use literal values.

DEFAULT - modifiability of the value is defined by ModificationFlags.isModifiable, ALWAYS/NEVER - the value can be always/never modified. Defaults to DEFAULT. Can't be used on properties inside a collection property.

Enum keys

Always | Default | Never

RangeConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

Range

RecursivePreconditionType

⚠️ Deprecated Use literal values.

Type also defines which properties are required.

Enum keys

And | Or

ReferentialIntegrityDeletionConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

ReferentialIntegrity

RegexConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

Regex

RegexMatchPreconditionType

⚠️ Deprecated Use literal values.

Type also defines which properties are required.

Enum keys

RegexMatch

ResourceContextOperationsItem

⚠️ Deprecated Use literal values.

Enum keys

Delete | Read | Write

RevisionDiffType

⚠️ Deprecated Use literal values.

The type of the difference.

Enum keys

Create | Delete | NoChange | Reorder | Update

SchemaStubMaturity

⚠️ Deprecated Use literal values.

The maturity of the schema.

Enum keys

EarlyAdopter | GeneralAvailability | Preview

SecretResubmissionContainerConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

SecretResubmission

SettingsObjectCreateInsertPosition

⚠️ Deprecated Use literal values.

Enum keys

After | Before | First | Last

SettingsObjectUpdateInsertPosition

⚠️ Deprecated Use literal values.

Enum keys

After | Before | First | Last

SettingsSchemaDefinitionMaturity

⚠️ Deprecated Use literal values.

The maturity of the schema. Possible values:

• PREVIEW: Preview features aren't generally available, but might be available in specific environments as part of early-access programs. These are the most likely to change in incompatible ways.
• EARLY_ADOPTER: Features marked "early adopter" are available in all environments, but aren't mature enough to warrant the "general availability" designation. We don't expect incompatible changes for these, but be aware, that these aren't fully stable yet and incompatible changes may be necessary in rare cases.
• GENERAL_AVAILABILITY: Features marked "general availability" are the most stable. While the schemas will still evolve over time, care will be taken to only do so in a backward-compatible manner.

In any case, automations should make use of the schemaVersion field when writing settings objects.

Enum keys

EarlyAdopter | GeneralAvailability | Preview

SinglePermissionRequestPermission

⚠️ Deprecated Use literal values.

Enum keys

SettingsObjectsAdmin | SettingsObjectsRead | SettingsObjectsWrite

TrimmedConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

Trimmed

UniqueMultiScopeSchemaPropertiesConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

MultiScopeUnique

UniquePropertiesConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

Unique

UniqueSchemaPropertiesConstraintType

⚠️ Deprecated Use literal values.

Type also defines which properties are available.

Enum keys

Unique