openapi: 3.2.0 info: title: dotCMS REST System Configuration API version: '3' description: System configuration and company settings servers: - url: / description: dotCMS Server tags: - name: System Configuration description: System configuration and company settings paths: /api/config/deleteEndpoint: post: tags: - System Configuration operationId: deleteEndpoint requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: user: type: string password: type: string endPoint: type: string type: type: string callback: type: string responses: default: description: default response content: application/json: {} deprecated: true summary: Delete endpoint x-summary-source: derived /api/config/deleteEnvironment: post: tags: - System Configuration operationId: deleteEnvironment requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: user: type: string password: type: string environment: type: string type: type: string callback: type: string responses: default: description: default response content: application/json: {} summary: Delete environment x-summary-source: derived /api/config/regenerateKey: post: tags: - System Configuration operationId: regenerateKey responses: default: description: default response content: application/json: {} summary: Regenerate key x-summary-source: derived /api/config/saveCompanyAuthTypeInfo: post: tags: - System Configuration operationId: saveCompanyAuthTypeInfo requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: user: type: string password: type: string authType: type: string responses: default: description: default response content: application/json: {} summary: Save company auth type info x-summary-source: derived /api/config/saveCompanyBasicInfo: post: tags: - System Configuration operationId: saveCompanyBasicInfo requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: user: type: string password: type: string portalURL: type: string mx: type: string emailAddress: type: string size: type: string type: type: string street: type: string homeURL: type: string city: type: string state: type: string responses: default: description: default response content: application/json: {} summary: Save company basic info x-summary-source: derived /api/config/saveCompanyLocaleInfo: post: tags: - System Configuration operationId: saveCompanyLocaleInfo requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: user: type: string password: type: string languageId: type: string timeZoneId: type: string responses: default: description: default response content: application/json: {} summary: Save company locale info x-summary-source: derived /api/config/saveCompanyLogo: post: tags: - System Configuration operationId: saveCompanyLogo requestBody: content: multipart/form-data: schema: type: object properties: user: type: string password: type: string logoFile: $ref: '#/components/schemas/FormDataContentDisposition' responses: default: description: default response content: text/html: {} deprecated: true summary: Save company logo x-summary-source: derived /api/v1/configuration/branding: get: tags: - System Configuration summary: Get company configuration description: Returns the full company configuration including branding, authentication settings, and metadata for the admin editing UI. operationId: getCompanyConfig responses: '200': description: Company configuration retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntityCompanyConfigView' '401': description: Unauthorized - authentication required content: application/json: {} '403': description: Forbidden - CMS Administrator role required content: application/json: {} put: tags: - System Configuration summary: Save company basic info and branding description: Updates the company's portal URL, email address, branding colors, logos, and background image. Navigation bar logo requires Enterprise license. operationId: saveBasicInfo requestBody: description: Company basic info and branding settings content: application/json: schema: $ref: '#/components/schemas/CompanyBasicInfoForm' required: true responses: '200': description: Company basic info updated successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntityCompanyConfigView' '400': description: Bad request - invalid parameters content: application/json: {} '401': description: Unauthorized - authentication required content: application/json: {} '403': description: Forbidden - CMS Administrator role required content: application/json: {} /api/v1/configuration/_regenerateKey: post: tags: - System Configuration summary: Regenerate company security key description: Regenerates the company's security key and returns the SHA-256 digest of the new key. This operation cannot be undone. operationId: regenerateKey_1 responses: '200': description: Security key regenerated successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntityStringView' '401': description: Unauthorized - authentication required content: application/json: {} '403': description: Forbidden - CMS Administrator role required content: application/json: {} /api/v1/configuration/authentication: put: tags: - System Configuration summary: Save company authentication type description: Updates the authentication method used for user login. Accepts 'emailAddress' or 'userId'. operationId: saveAuthType requestBody: description: Authentication type setting content: application/json: schema: $ref: '#/components/schemas/CompanyAuthTypeForm' required: true responses: '200': description: Authentication type updated successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntityCompanyConfigView' '400': description: Bad request - invalid auth type content: application/json: {} '401': description: Unauthorized - authentication required content: application/json: {} '403': description: Forbidden - CMS Administrator role required content: application/json: {} /api/v1/configuration/locale: put: tags: - System Configuration summary: Save company locale info description: Updates the locale (language and timezone) for the current company. This sets the default language and timezone for the system. operationId: saveLocaleInfo requestBody: description: Locale settings to apply content: application/json: schema: $ref: '#/components/schemas/CompanyLocaleForm' required: true responses: '200': description: Locale settings updated successfully content: application/json: schema: $ref: '#/components/schemas/ResponseEntityCompanyConfigView' '400': description: Invalid locale parameters (e.g. invalid timezone) content: application/json: {} '401': description: Unauthorized - authentication required content: application/json: {} '403': description: Forbidden - CMS Administrator role required content: application/json: {} /api/v1/appconfiguration: get: tags: - System Configuration operationId: list_5 responses: default: description: default response content: application/json: {} application/javascript: {} summary: List 5 x-summary-source: derived /api/v1/configuration/config: get: tags: - System Configuration summary: Retrieve whitelisted configuration values description: Returns a map of configuration key to value for each requested key that is present in the server whitelist. Boolean feature-flag keys (those in BOOLEAN_FEATURE_FLAGS) are normalised to the lowercase strings "true" or "false" regardless of how they are stored in the properties file; undefined flags return the sentinel string "NOT_FOUND". Keys prefixed with "number:" return an Integer, "list:" returns an array of strings, "boolean:" returns a native JSON boolean. All other whitelisted keys return their raw string value. Keys not on the whitelist are silently excluded. operationId: getConfigVariables parameters: - name: keys in: query schema: type: string responses: '200': description: Map of key to configuration value content: application/json: schema: type: object description: 'Map of configuration key to value. Value type depends on the key: normalised string "true"/"false" for boolean feature flags, "NOT_FOUND" for undefined flags, Integer for number:-prefixed keys, array for list:-prefixed keys, native boolean for boolean:-prefixed keys, raw string otherwise.' example: FEATURE_FLAG_EXPERIMENTS: 'true' EMAIL_SYSTEM_ADDRESS: admin@example.com FEATURE_FLAG_UVE_STYLE_EDITOR: NOT_FOUND '401': description: User is not authenticated /api/v1/configuration: get: tags: - System Configuration operationId: list_6 responses: default: description: default response content: application/json: {} application/javascript: {} summary: List 6 x-summary-source: derived put: tags: - System Configuration operationId: set requestBody: content: application/json: schema: type: object additionalProperties: type: string responses: default: description: default response content: '*/*': {} summary: Set x-summary-source: derived /api/v1/configuration/_validateCompanyEmail: post: tags: - System Configuration operationId: validateEmail requestBody: content: '*/*': schema: $ref: '#/components/schemas/CompanyEmailForm' responses: default: description: default response content: application/json: {} application/javascript: {} summary: Validate email x-summary-source: derived /api/v1/system-table/{key}: get: tags: - System Configuration operationId: get_4 parameters: - name: key in: path required: true schema: type: string responses: default: description: default response content: application/json: schema: $ref: '#/components/schemas/ResponseEntityStringView' application/javascript: schema: $ref: '#/components/schemas/ResponseEntityStringView' summary: Get 4 x-summary-source: derived delete: tags: - System Configuration operationId: delete_9 parameters: - name: key in: path required: true schema: type: string responses: default: description: default response content: application/json: schema: $ref: '#/components/schemas/ResponseEntityStringView' application/javascript: schema: $ref: '#/components/schemas/ResponseEntityStringView' summary: Delete 9 x-summary-source: derived /api/v1/system-table/_delete: delete: tags: - System Configuration operationId: deleteWithKey requestBody: content: application/json: schema: type: object additionalProperties: type: string responses: default: description: default response content: application/json: schema: $ref: '#/components/schemas/ResponseEntityStringView' application/javascript: schema: $ref: '#/components/schemas/ResponseEntityStringView' summary: Delete with key x-summary-source: derived /api/v1/system-table: get: tags: - System Configuration operationId: getAll_2 responses: default: description: default response content: application/json: schema: $ref: '#/components/schemas/ResponseEntityViewMapStringString' application/javascript: schema: $ref: '#/components/schemas/ResponseEntityViewMapStringString' summary: Get all 2 x-summary-source: derived put: tags: - System Configuration summary: Updates an existing system table entry description: 'Updates the value of an existing key in the system table, or returns a 404 if the key does not exist. The change is applied cluster wide: every node is notified and re-resolves the key, so the request does not need to be repeated against each node.' operationId: update_8 requestBody: content: application/json: schema: $ref: '#/components/schemas/KeyValueForm' responses: default: description: default response content: application/json: schema: $ref: '#/components/schemas/ResponseEntityStringView' application/javascript: schema: $ref: '#/components/schemas/ResponseEntityStringView' post: tags: - System Configuration summary: Saves or updates a system table entry description: 'Saves or updates the value of a key in the system table. The change is applied cluster wide: every node is notified and re-resolves the key, so the request does not need to be repeated against each node.' operationId: save requestBody: content: '*/*': schema: $ref: '#/components/schemas/KeyValueForm' responses: default: description: default response content: application/json: schema: $ref: '#/components/schemas/ResponseEntityStringView' application/javascript: schema: $ref: '#/components/schemas/ResponseEntityStringView' components: schemas: KeyValueForm: required: - key - value type: object properties: key: type: string value: type: string Pagination: type: object properties: currentPage: type: integer format: int32 perPage: type: integer format: int32 totalEntries: type: integer format: int64 CompanyLocaleForm: required: - languageId - timeZoneId type: object properties: languageId: type: string description: Java locale string example: en_US timeZoneId: type: string description: Java TimeZone ID example: America/New_York description: Company locale settings (language and timezone) CompanyAuthTypeForm: required: - authType type: object properties: authType: type: string description: 'Authentication type: ''emailAddress'' or ''userId''' example: emailAddress enum: - emailAddress - userId - emailAddress - userId description: Company authentication type setting ResponseEntityCompanyConfigView: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorEntity' entity: $ref: '#/components/schemas/CompanyConfigView' messages: type: array items: $ref: '#/components/schemas/MessageEntity' i18nMessagesMap: type: object additionalProperties: type: string permissions: type: array items: type: string pagination: $ref: '#/components/schemas/Pagination' CompanyEmailForm: type: object properties: senderAndEmail: type: string MessageEntity: type: object properties: message: type: string ResponseEntityViewMapStringString: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorEntity' entity: type: object additionalProperties: type: string messages: type: array items: $ref: '#/components/schemas/MessageEntity' i18nMessagesMap: type: object additionalProperties: type: string permissions: type: array items: type: string pagination: $ref: '#/components/schemas/Pagination' ResponseEntityStringView: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorEntity' entity: type: string messages: type: array items: $ref: '#/components/schemas/MessageEntity' i18nMessagesMap: type: object additionalProperties: type: string permissions: type: array items: type: string pagination: $ref: '#/components/schemas/Pagination' CompanyBasicInfoForm: required: - emailAddress - portalURL - primaryColor - secondaryColor type: object properties: portalURL: type: string description: Portal URL for the dotCMS instance example: http://localhost:8080 emailAddress: type: string description: Company email address used as the system sender. Accepts plain email (e.g. 'admin@dotcms.com') or display name format (e.g. 'dotCMS Website '). The mx domain is derived from this value when mx is not provided. example: admin@dotcms.com mx: type: string description: Mail exchange domain (derived from emailAddress if not provided) example: dotcms.com primaryColor: type: string description: Primary branding color (hex) example: '#C336E5' secondaryColor: type: string description: Secondary branding color (hex) example: '#54428E' backgroundColor: type: string description: Background branding color (hex). Cleared if omitted. example: '#3C1361' backgroundImage: type: string description: Background image path (dotAsset path starting with /dA). Cleared if omitted. example: /dA/abc123/background.png loginScreenLogo: type: string description: Login screen logo path (dotAsset path starting with /dA). Cleared if omitted. example: /dA/abc123/logo.png navBarLogo: type: string description: Navigation bar logo path (dotAsset path starting with /dA, Enterprise only). Cleared if omitted. example: /dA/abc123/nav-logo.png description: Company basic information and branding settings FormDataContentDisposition: type: object properties: type: type: string parameters: type: object additionalProperties: type: string fileName: type: string creationDate: type: string format: date-time modificationDate: type: string format: date-time readDate: type: string format: date-time size: type: integer format: int64 name: type: string ErrorEntity: type: object properties: errorCode: type: string message: type: string fieldName: type: string CompanyConfigView: required: - authType - companyId - companyName - emailAddress - mx - portalURL type: object properties: companyId: type: string description: Company identifier example: dotcms.org companyName: type: string description: Company display name example: dotcms.org portalURL: type: string description: Portal URL for the dotCMS instance example: http://localhost:8080 emailAddress: type: string description: Company email address used as the system sender. May be a plain email or display name format (e.g. 'dotCMS Website ') example: admin@dotcms.com mx: type: string description: Mail exchange domain for outgoing email example: dotcms.com primaryColor: type: string description: Primary branding color (hex) example: '#C336E5' secondaryColor: type: string description: Secondary branding color (hex) example: '#54428E' backgroundColor: type: string description: Background branding color (hex) example: '#3C1361' backgroundImage: type: string description: Background image path (dotAsset path starting with /dA) example: /dA/abc123/background.png loginScreenLogo: type: string description: Login screen logo path (dotAsset path starting with /dA) example: /dA/abc123/logo.png navBarLogo: type: string description: Navigation bar logo path (dotAsset path starting with /dA, Enterprise only) example: /dA/abc123/nav-logo.png authType: type: string description: 'Authentication type: ''emailAddress'' or ''userId''' example: emailAddress enum: - emailAddress - userId keyDigest: type: string description: SHA-256 digest of the company security key (read-only, admin only) languageId: type: string description: System default language as a Java locale string example: en_US timeZoneId: type: string description: System default timezone ID example: America/New_York