mc8yp 2.6.2 → 2.7.1

package/dist/cli.mjs

@@ -1546,7 +1546,7 @@ const consola = createConsola();
 //#endregion
 //#region package.json
 var name = "mc8yp";
-var version = "2.6.2";
+var version = "2.7.1";
 var description$1 = "Cumulocity IoT MCP Server - Model Context Protocol integration for IoT device management";
 //#endregion
 //#region \0virtual:core-openapi
@@ -5390,7 +5390,7 @@ const specs = Object.freeze([
 						"operationId": "putCRLSettings",
 						"tags": ["Trusted certificates"],
 						"summary": "Add revoked certificates",
-						"description": "> **&#9432; Info:** A certificate revocation list (CRL) is a list of digital certificates\n   that have been revoked by the issuing certificate authority (CA) before expiration date.\n   In Cumulocity, a CRL check can be in online or offline mode or both.\n\nAn endpoint to add revoked certificate serial numbers for offline CRL check via payload or file.\n\nFor payload, a JSON object required with list of CRL entries, for example:\n ```json\n   {\n    \"crls\": [\n      {\n        \"serialNumberInHex\": \"1000\",\n        \"revocationDate\": \"2023-01-11T16:12:36.288Z\"\n      }\n     ]\n    }\n  ```\nEach entry is composed of:\n * serialNumberInHex: Needs to be in `Hexadecimal Value`. e.g As (1000)^16 == (4096)^10, So we have to enter 1000.\n    If duplicate serial number exists in payload, the existing entry stays</br>\n * `revocationDate` - accepted Date format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`, for example: `2023-01-11T16:12:36.288Z`.\n     This is an optional parameter and defaults to the current server UTC date time if not specified in the payload.\n     If specified and the date is in future then those entries will be also defaulted to current date.\n\nFor file upload, each file can hold at maximum 5000 revocation entries.\nMultiple upload is allowed.\nIn case of duplicates, the latest (last uploaded) entry is considered.\n\nSee below for a sample CSV file:\n\n| SERIAL NO.  | REVOCATION DATE |\n|--|--|\n| 1000 | 2023-01-11T16:12:36.288Z |\n\n Each entry is composed of :\n * serialNumberInHex: Needs to be in `Hexadecimal Value`. e.g (1000)^16 == (4096)^10, So we have to enter 1000.\n    If duplicate serial number exists in payload, the latest entry will be taken.</br>\n * revocationDate: Accepted Date format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` e.g: 2023-01-11T16:12:36.288Z.\n This is an optional and will be default to current server UTC date time if not specified in payload.\n If specified and the date is in future then those entries will be skipped.\n\nThe CRL setting for offline and online check can be enabled/disabled using <kbd><a href=\"#operation/putOptionResource\">/tenant/options</a></kbd>.\nKeys are `crl.online.check.enabled` and `crl.offline.check.enabled` under the category `configuration`.\n\n<section><h5>Required roles</h5>\n(ROLE_TENANT_MANAGEMENT_ADMIN <b>OR</b> ROLE_TENANT_ADMIN) <b>AND</b> is the current tenant\n</section>\n\n**⚠️ Important:** According to CRL policy, added serial numbers cannot be reversed.\n",
+						"description": "> **&#9432; Info:** A certificate revocation list (CRL) is a list of digital certificates\n   that have been revoked by the issuing certificate authority (CA) before expiration date.\n   In Cumulocity, a CRL check can be in online or offline mode or both.\n\nAn endpoint to add revoked certificate serial numbers for offline CRL check via payload or file.\nA file can be uploaded with either `PUT` or `POST`, a JSON payload is accepted by `PUT` only.\n\nFor payload, a JSON object required with list of CRL entries, for example:\n ```json\n   {\n    \"crls\": [\n      {\n        \"serialNumberInHex\": \"1000\",\n        \"revocationDate\": \"2023-01-11T16:12:36.288Z\"\n      }\n     ]\n    }\n  ```\nEach entry is composed of:\n * serialNumberInHex: Needs to be in `Hexadecimal Value`. e.g As (1000)^16 == (4096)^10, So we have to enter 1000.\n    If duplicate serial number exists in payload, the existing entry stays</br>\n * `revocationDate` - accepted Date format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`, for example: `2023-01-11T16:12:36.288Z`.\n     This is an optional parameter and defaults to the current server UTC date time if not specified in the payload.\n     If specified and the date is in future then those entries will be also defaulted to current date.\n\nFor file upload, each file can hold at maximum 5000 revocation entries.\nMultiple upload is allowed.\nIn case of duplicates, the latest (last uploaded) entry is considered.\n\nSee below for a sample CSV file:\n\n| SERIAL NO.  | REVOCATION DATE |\n|--|--|\n| 1000 | 2023-01-11T16:12:36.288Z |\n\n Each entry is composed of :\n * serialNumberInHex: Needs to be in `Hexadecimal Value`. e.g (1000)^16 == (4096)^10, So we have to enter 1000.\n    If duplicate serial number exists in payload, the latest entry will be taken.</br>\n * revocationDate: Accepted Date format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` e.g: 2023-01-11T16:12:36.288Z.\n This is an optional and will be default to current server UTC date time if not specified in payload.\n If specified and the date is in future then those entries will be skipped.\n\nThe CRL setting for offline and online check can be enabled/disabled using <kbd><a href=\"#operation/putOptionResource\">/tenant/options</a></kbd>.\nKeys are `crl.online.check.enabled` and `crl.offline.check.enabled` under the category `configuration`.\n\n<section><h5>Required roles</h5>\n(ROLE_TENANT_MANAGEMENT_ADMIN <b>OR</b> ROLE_TENANT_ADMIN) <b>AND</b> is the current tenant\n</section>\n\n**⚠️ Important:** According to CRL policy, added serial numbers cannot be reversed.\n",
 						"requestBody": {
 							"required": true,
 							"content": {
@@ -5408,6 +5408,25 @@ const specs = Object.freeze([
 						},
 						"responses": { "204": { "description": "CRLs updated successfully." } }
 					},
+					"post": {
+						"operationId": "postCRLSettings",
+						"tags": ["Trusted certificates"],
+						"summary": "Add revoked certificates",
+						"description": "> **&#9432; Info:** A certificate revocation list (CRL) is a list of digital certificates\n   that have been revoked by the issuing certificate authority (CA) before expiration date.\n   In Cumulocity, a CRL check can be in online or offline mode or both.\n\nAn endpoint to add revoked certificate serial numbers for offline CRL check via payload or file.\nA file can be uploaded with either `PUT` or `POST`, a JSON payload is accepted by `PUT` only.\n\nFor payload, a JSON object required with list of CRL entries, for example:\n ```json\n   {\n    \"crls\": [\n      {\n        \"serialNumberInHex\": \"1000\",\n        \"revocationDate\": \"2023-01-11T16:12:36.288Z\"\n      }\n     ]\n    }\n  ```\nEach entry is composed of:\n * serialNumberInHex: Needs to be in `Hexadecimal Value`. e.g As (1000)^16 == (4096)^10, So we have to enter 1000.\n    If duplicate serial number exists in payload, the existing entry stays</br>\n * `revocationDate` - accepted Date format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`, for example: `2023-01-11T16:12:36.288Z`.\n     This is an optional parameter and defaults to the current server UTC date time if not specified in the payload.\n     If specified and the date is in future then those entries will be also defaulted to current date.\n\nFor file upload, each file can hold at maximum 5000 revocation entries.\nMultiple upload is allowed.\nIn case of duplicates, the latest (last uploaded) entry is considered.\n\nSee below for a sample CSV file:\n\n| SERIAL NO.  | REVOCATION DATE |\n|--|--|\n| 1000 | 2023-01-11T16:12:36.288Z |\n\n Each entry is composed of :\n * serialNumberInHex: Needs to be in `Hexadecimal Value`. e.g (1000)^16 == (4096)^10, So we have to enter 1000.\n    If duplicate serial number exists in payload, the latest entry will be taken.</br>\n * revocationDate: Accepted Date format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` e.g: 2023-01-11T16:12:36.288Z.\n This is an optional and will be default to current server UTC date time if not specified in payload.\n If specified and the date is in future then those entries will be skipped.\n\nThe CRL setting for offline and online check can be enabled/disabled using <kbd><a href=\"#operation/putOptionResource\">/tenant/options</a></kbd>.\nKeys are `crl.online.check.enabled` and `crl.offline.check.enabled` under the category `configuration`.\n\n<section><h5>Required roles</h5>\n(ROLE_TENANT_MANAGEMENT_ADMIN <b>OR</b> ROLE_TENANT_ADMIN) <b>AND</b> is the current tenant\n</section>\n\n**⚠️ Important:** According to CRL policy, added serial numbers cannot be reversed.\n",
+						"requestBody": {
+							"required": true,
+							"content": { "multipart/form-data": { "schema": {
+								"type": "object",
+								"required": ["file"],
+								"properties": { "file": {
+									"description": "File to be uploaded.",
+									"type": "string",
+									"format": "binary"
+								} }
+							} } }
+						},
+						"responses": { "204": { "description": "CRLs updated successfully." } }
+					},
 					"get": {
 						"operationId": "getCRLSettings",
 						"tags": ["Trusted certificates"],
@@ -5888,7 +5907,11 @@ const specs = Object.freeze([
 				} },
 				"/tenant/oauth": { "post": {
 					"operationId": "postLoginFormCookie",
-					"parameters": [{ "$ref": "#/components/parameters/queryParam_tenant_id" }, { "$ref": "#/components/parameters/acceptHeader" }],
+					"parameters": [
+						{ "$ref": "#/components/parameters/queryParam_tenant_id" },
+						{ "$ref": "#/components/parameters/tfaCodeHeader" },
+						{ "$ref": "#/components/parameters/acceptHeader" }
+					],
 					"tags": ["Login tokens"],
 					"summary": "Obtain access tokens in cookies",
 					"description": "Obtain an OAI-Secure and XSRF tokens in cookies.\n",
@@ -5914,7 +5937,11 @@ const specs = Object.freeze([
 				} },
 				"/tenant/oauth/token": { "post": {
 					"operationId": "postLoginFormBody",
-					"parameters": [{ "$ref": "#/components/parameters/queryParam_tenant_id" }, { "$ref": "#/components/parameters/acceptHeader" }],
+					"parameters": [
+						{ "$ref": "#/components/parameters/queryParam_tenant_id" },
+						{ "$ref": "#/components/parameters/tfaCodeHeader" },
+						{ "$ref": "#/components/parameters/acceptHeader" }
+					],
 					"tags": ["Login tokens"],
 					"summary": "Obtain an access token",
 					"description": "Obtain an OAI-Secure access token.",
@@ -5927,6 +5954,32 @@ const specs = Object.freeze([
 						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/accessToken" } } }
 					} }
 				} },
+				"/tenant/oauth/certificate": { "post": {
+					"operationId": "postCertificateAccessToken",
+					"parameters": [
+						{ "$ref": "#/components/parameters/queryParam_tenant_id" },
+						{ "$ref": "#/components/parameters/tenantIdInHeader" },
+						{ "$ref": "#/components/parameters/tokenResponseModeHeader" },
+						{ "$ref": "#/components/parameters/tfaCodeHeader" },
+						{ "$ref": "#/components/parameters/acceptHeader" }
+					],
+					"tags": ["Login tokens"],
+					"summary": "Obtain an access token with a certificate",
+					"description": "Obtain a platform access token by presenting an X.509 certificate over standard HTTPS, without requiring mutual TLS (mTLS) or MQTT. This provides a REST-native, standard-port alternative for certificate-authenticated clients that cannot use MQTT or the dedicated mTLS endpoint.\n\nThe request body contains the leaf certificate, or the full certificate chain, in PEM format. By default the returned access token is encrypted as a JWE with the public key from the presented certificate, so that only the holder of the corresponding private key can decrypt it and use it as a `Bearer` token for subsequent REST API requests. The response format can be controlled with the `X-Cumulocity-Token-Response-Mode` header. JWE mode requires the certificate to use an RSA key, because the platform encrypts the token with `RSA-OAEP-256`; clients presenting a certificate with a non-RSA key must request a plain JWT with the `X-Cumulocity-Token-Response-Mode: jwt` header.\n\nThe platform derives the identity from the certificate subject, validates the certificate material against the tenant-trusted certificate authorities (including validity dates and revocation checks where configured) and confirms that the certificate is authorized for the resolved user. The tenant context must be established from the request before validation, for example through the `tenant_id` query parameter or the `X-Cumulocity-TenantId` header. The certificate is not used as the primary tenant identification mechanism.\n\nIf the resolved certificate identity is ambiguous, for example when the same certificate common name could resolve to both a regular user and a device user, the request is rejected and no token is issued. Untrusted, expired, revoked, malformed, unsupported or unmapped certificates are rejected as well.\n\nIf two-factor authentication (TFA) is active for the resolved user, it must be passed with the request as well, because the certificate replaces the password, not the second factor. Send the current TFA code in the `X-Cumulocity-TFA-Code` header. Both the TOTP and the SMS strategy are supported, in the same way as for the OAI-Secure login. Device users are never asked for a second factor.\n",
+					"requestBody": {
+						"required": true,
+						"content": { "application/x-pem-file": { "schema": {
+							"type": "string",
+							"format": "binary",
+							"description": "Leaf certificate or full certificate chain in PEM format.",
+							"example": "-----BEGIN CERTIFICATE-----\nMIIDTzCCAjegAwIBAgIUB1a5GM9ubBpN5tyU7YO8D3C8zUUwDQYJKoZIhvcNAQEL\n...\nzngrsOfyKr8YYlDRy6RiAR2HQode00Hs4WoakfuTpaISZIs=\n-----END CERTIFICATE-----"
+						} } }
+					},
+					"responses": { "200": {
+						"description": "The access token is sent in the response. By default it is a JWE encrypted with the public key from the presented certificate.",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/certificateAccessToken" } } }
+					} }
+				} },
 				"/tenant/options": {
 					"post": {
 						"operationId": "postOptionCollectionResource",
@@ -6197,6 +6250,26 @@ const specs = Object.freeze([
 							"example": "t07007007"
 						}
 					},
+					"tokenResponseModeHeader": {
+						"name": "X-Cumulocity-Token-Response-Mode",
+						"in": "header",
+						"description": "Optional. Selects the format of the returned access token. `jwe` (default) returns the access token as a JWE encrypted with the public key from the presented certificate (RSA-OAEP-256 for key encryption and AES-256-GCM for content encryption), so that only the holder of the corresponding private key can decrypt it; it requires the certificate to use an RSA key. `jwt` returns a plain, unencrypted JWT and is rejected with a 403 error unless plain JWT responses are enabled for the platform or the certificate does not use an RSA key. Unsupported values are rejected with a 400 error.\n",
+						"schema": {
+							"type": "string",
+							"enum": ["jwe", "jwt"],
+							"default": "jwe",
+							"example": "jwe"
+						}
+					},
+					"tfaCodeHeader": {
+						"name": "X-Cumulocity-TFA-Code",
+						"in": "header",
+						"description": "Optional. Current TFA code of the user, if a TFA code is required to log in. For form-based OAI-Secure login, the code can be sent as the `tfa_code` field in the request body; this header is useful for requests that cannot include that field (for example when the request body is a certificate chain). If both are sent, the request body field takes precedence.\n",
+						"schema": {
+							"type": "string",
+							"example": "123433"
+						}
+					},
 					"alarmId": {
 						"name": "id",
 						"in": "path",
@@ -8427,6 +8500,17 @@ const specs = Object.freeze([
 							}
 						} }
 					},
+					"jweUnsupportedCertificateKeyUnprocessableEntity": {
+						"description": "The presented certificate does not use an RSA key, so the access token cannot be encrypted as a JWE. Request a plain JWT with the `X-Cumulocity-Token-Response-Mode: jwt` header instead.\n",
+						"content": { "application/vnd.com.nsn.cumulocity.error+json": {
+							"schema": { "$ref": "#/components/schemas/error" },
+							"example": {
+								"error": "certificate-token/Unprocessable Entity",
+								"message": "Only RSA certificates are supported for JWE mode. Use header X-Cumulocity-Token-Response-Mode: jwt for non-RSA certificates.",
+								"info": "https://www.cumulocity.com/guides/reference-guide/#error_reporting"
+							}
+						} }
+					},
 					"unableToParseCRLEntries": {
 						"description": "Unsupported date time format.",
 						"content": { "application/vnd.com.nsn.cumulocity.error+json": {
@@ -14584,6 +14668,33 @@ const specs = Object.freeze([
 							}
 						}
 					},
+					"certificateAccessToken": {
+						"description": "Access token obtained by presenting an X.509 certificate. By default the token is returned as a JWE encrypted with the public key from the presented certificate, so that only the holder of the corresponding private key can decrypt it. This requires the certificate to use an RSA key, because the platform encrypts the token with `RSA-OAEP-256`.\n\nA plain, unencrypted JWT can be requested with the `X-Cumulocity-Token-Response-Mode: jwt` header, but such requests are rejected with a 403 error unless plain JWT responses have been explicitly enabled for the platform. Clients whose certificate does not use an RSA key are exempt from that restriction, as JWE mode is not available to them: they may always request `jwt`, and must do so, because a request left in the default `jwe` mode is rejected with a 422 error.\n",
+						"type": "object",
+						"properties": {
+							"access_token": {
+								"description": "The access token generated by the Cumulocity platform. A JWE compact-serialized, encrypted JWT when `response_mode` is `jwe`, or a plain, unencrypted JWT when `response_mode` is `jwt`.",
+								"type": "string",
+								"example": "eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0.g_hEwksO1Ax8Qn7HoN-BVeBoa8FXe0kpyk_XdcSmxvcM5_P296JXXtoHISr_DD_M...48V95cLzdVlCyoQ"
+							},
+							"token_type": {
+								"description": "The type of the returned token.",
+								"type": "string",
+								"example": "Bearer"
+							},
+							"response_mode": {
+								"description": "The format of the returned access token. `jwe` unless a plain JWT was requested with the `X-Cumulocity-Token-Response-Mode` header and permitted.",
+								"type": "string",
+								"enum": ["jwe", "jwt"],
+								"example": "jwe"
+							},
+							"expires_in": {
+								"description": "The token lifetime in seconds.",
+								"type": "integer",
+								"example": 3600
+							}
+						}
+					},
 					"SystemOptionCollection": {
 						"description": "All available system options of the tenant.",
 						"type": "object",
@@ -58548,17 +58659,17 @@ function buildMcpTools(server) {
 	return tools;
 }
 /**
-* Build the per-connection namespace list: core as `c8y` plus one namespace
-* per available service. A service exposing an MCP server becomes an MCP
-* namespace (its spec is skipped) unless opted out via `noMcp` — then its
-* spec is used as the fallback. Operations blocked by the connection policy
-* are omitted from OpenAPI namespaces; path templates are matched as-is.
+* Build the per-connection namespace list: core as `c8y`, one namespace per
+* available service, then one per connection-supplied external MCP server. A
+* service exposing an MCP server becomes an MCP namespace (its spec is skipped)
+* unless opted out via `noMcp` — then its spec is used as the fallback.
+* Operations blocked by the connection policy are omitted from OpenAPI
+* namespaces; path templates are matched as-is.
 * @param resolved
-* @param restrictions
-* @param allowRules
-* @param noMcp Per-connection MCP-wrapping opt-out.
+* @param options Per-connection policy, opt-outs, and external servers.
 */
-function buildNamespaces(resolved, restrictions = [], allowRules = [], noMcp) {
+function buildNamespaces(resolved, options = {}) {
+	const { restrictions = [], allowRules = [], noMcp, externalServers = [] } = options;
 	const visibleOperations = (spec) => deriveOperations(spec).filter((op) => !evaluateAccessPolicy(restrictions, allowRules, op.method, op.path).blocked);
 	const namespaces = [{
 		kind: "openapi",
@@ -58601,6 +58712,31 @@ function buildNamespaces(resolved, restrictions = [], allowRules = [], noMcp) {
 			});
 		}
 	}
+	for (const external of externalServers) {
+		const name = external.config.name;
+		if (RESERVED_NAMESPACES.has(name) || used.has(name)) {
+			consola.warn(`[codemode] external MCP server "${name}" (${external.config.url}) maps to a namespace that is ${RESERVED_NAMESPACES.has(name) ? "reserved" : "already used by this tenant"} — skipping this server.`);
+			continue;
+		}
+		used.add(name);
+		const server = {
+			contextPath: name,
+			appLabel: name,
+			mcpName: name,
+			description: external.config.description ?? external.instructions,
+			url: external.config.url,
+			sendAuthentication: false,
+			tools: external.tools
+		};
+		namespaces.push({
+			kind: "mcp",
+			name,
+			specKey: name,
+			external: external.config,
+			server,
+			tools: buildMcpTools(server)
+		});
+	}
 	return namespaces;
 }
 /**
@@ -58664,7 +58800,12 @@ function createCodeModeGuidePrompt() {
 		const restrictions = c8yMcpServer.ctx.custom?.restrictions ?? [];
 		const allowRules = c8yMcpServer.ctx.custom?.allowRules ?? [];
 		const resolvedSpecs = c8yMcpServer.ctx.custom?.specs;
-		const namespaceNames = resolvedSpecs ? buildNamespaces(resolvedSpecs, restrictions, allowRules).map((ns) => ns.name) : ["c8y"];
+		const namespaceNames = [...resolvedSpecs ? buildNamespaces(resolvedSpecs, {
+			restrictions,
+			allowRules
+		}).map((ns) => ns.name) : ["c8y"], ...(c8yMcpServer.ctx.custom?.externalMcpServers ?? []).map((s) => s.name)];
+		const externalServers = c8yMcpServer.ctx.custom?.externalMcpServers ?? [];
+		const externalLine = externalServers.length > 0 ? `\n- ${externalServers.map((s) => `\`${s.name}\``).join(", ")} ${externalServers.length === 1 ? "is an" : "are"} external MCP server${externalServers.length === 1 ? "" : "s"} configured for THIS connection — not part of the tenant. Same typed-method surface; describe and search work identically.` : "";
 		const policyLines = [...restrictions.map((rule) => `- deny: \`${rule.source}\``), ...allowRules.map((rule) => `- allow: \`${rule.source}\``)];
 		const restrictionSection = policyLines.length > 0 ? `\n## Current Connection Access Policy\n${policyLines.join("\n")}\n\nOperations blocked by these rules are omitted from discovery (search/describe) entirely, and any live request that matches a deny rule (or misses the allow list) fails before reaching the tenant.\n` : "";
 		const sandboxSection = c8yMcpServer.ctx.custom?.env === "server" && c8yMcpServer.ctx.custom?.enableSandbox ? `\n## Sandbox (scratch compute)
@@ -58707,7 +58848,7 @@ declare const docs: {
 API namespaces currently visible: ${namespaceNames.map((n) => `\`${n}\``).join(", ")}.
 
 - \`c8y\` is the Cumulocity core REST surface (inventory, alarms, events, measurements, identity, device control, users, tenants, audit). Always present.
-- Each additional namespace is a microservice available on the current tenant (e.g. \`dtm\`). A namespace exists only when the service is actually reachable.
+- Each additional namespace is a microservice available on the current tenant (e.g. \`dtm\`). A namespace exists only when the service is actually reachable.${externalLine}
 - Every namespace has one typed method per API operation. The namespaces are the complete surface — there is no raw-request escape hatch. If a method seems missing, re-search with different wording; if it truly does not exist, report that instead of improvising.
 - Method inputs are a single flat object: path/query/header parameters as top-level keys, the request payload under \`body\`.
 
@@ -77296,7 +77437,18 @@ const indexCache$1 = /* @__PURE__ */ new WeakMap();
 function getMethodIndex(cacheKey, items) {
 	const cached = indexCache$1.get(cacheKey);
 	if (cached) return cached;
-	const list = items();
+	const index = buildMethodIndex(items());
+	indexCache$1.set(cacheKey, index);
+	return index;
+}
+/**
+* Build an index without caching it. Used for connection-scoped method sets
+* (external MCP namespaces): those cannot enter the per-tenant cache, and
+* indexing a few hundred short documents costs single-digit milliseconds
+* against a codemode call measured in seconds.
+* @param list
+*/
+function buildMethodIndex(list) {
 	const mini = new MiniSearch({
 		idField: "target",
 		fields: [
@@ -77308,12 +77460,10 @@ function getMethodIndex(cacheKey, items) {
 		tokenize
 	});
 	mini.addAll([...list]);
-	const index = {
+	return {
 		mini,
 		methods: new Map(list.map((m) => [m.target, m]))
 	};
-	indexCache$1.set(cacheKey, index);
-	return index;
 }
 /**
 * Search the method index with one query or several phrasings at once
@@ -77542,7 +77692,7 @@ function truncateLine(text) {
 	return flattened.length > 220 ? `${flattened.slice(0, 220)}…` : flattened;
 }
 const SANDBOX_METHOD_COUNT = (SANDBOX_INTERFACE_TS.match(/^ {2}\w+:/gm) ?? []).length;
-function renderOverview(namespaces, sandboxEnabled) {
+function renderOverview(namespaces, sandboxEnabled, externalFailures) {
 	const lines = ["Available namespaces on this tenant (do not assume capabilities from prior knowledge — search each relevant domain):"];
 	for (const ns of namespaces) if (ns.kind === "openapi") {
 		const info = ns.spec.info;
@@ -77550,9 +77700,14 @@ function renderOverview(namespaces, sandboxEnabled) {
 		lines.push(`- ${ns.name}${info?.title ? ` — ${info.title}` : ""} (${ns.operations.length} methods)${short ? `: ${short}` : ""}`);
 	} else {
 		const short = truncateLine(ns.server.description);
-		lines.push(`- ${ns.name} — ${ns.server.mcpName} (${ns.tools.length} methods)${short ? `: ${short}` : ""}`);
+		const label = ns.external ? `EXTERNAL MCP server at ${ns.external.url} — configured for this connection, NOT part of this tenant` : ns.server.mcpName;
+		lines.push(`- ${ns.name} — ${label} (${ns.tools.length} methods)${short ? `: ${short}` : ""}`);
 	}
 	if (sandboxEnabled) lines.push(`- sandbox — in-memory shell + virtual filesystem (${SANDBOX_METHOD_COUNT} methods): jq/awk/grep/sed/sort/sqlite over data you fetched; no network, no host FS. codemode.describe("sandbox") for its methods.`);
+	if (externalFailures.length > 0) {
+		lines.push("", "Configured but unreachable right now (report this to the user; retrying may work if it is transient):");
+		for (const failure of externalFailures) lines.push(`- ${failure.name} (${failure.url}): ${failure.reason}`);
+	}
 	lines.push("", "Workflow:", "- codemode.search(\"keywords\") — find methods by name/path/summary (top 20 by score)", "- codemode.describe(\"<namespace>.<method>\") — types and docs for one method", "- docs.search(\"keywords\") / docs.read(id) — documentation topics (domain query languages, concepts)", "- <namespace>.<method>({ ...params, body }) — call the API");
 	return lines.join("\n");
 }
@@ -77584,6 +77739,7 @@ function renderMcpTool(namespace, tool) {
 		outputSchema: tool.outputSchema
 	});
 	const lines = [`${namespace.name}.${tool.name}`];
+	if (namespace.external) lines.push("", `External MCP server (${namespace.external.url}) — configured for this MCP connection, not part of this tenant. Calls go to that host with its own credentials; tenant credentials are never sent.`);
 	if (tool.description) lines.push("", tool.description);
 	lines.push("", "```ts", signature, "", types, "```");
 	return lines.join("\n");
@@ -77624,14 +77780,15 @@ function renderSearchRedirect(target, namespaces, methodIndex) {
 * @param namespaces
 * @param methodIndex
 * @param target
-* @param sandboxEnabled - whether the opt-in `sandbox` surface is exposed this run.
+* @param options Run-scoped extras for the overview.
 */
-function describeTarget(namespaces, methodIndex, target, sandboxEnabled = false) {
+function describeTarget(namespaces, methodIndex, target, options = {}) {
+	const { sandboxEnabled = false, externalFailures = [] } = options;
 	const trimmed = target?.trim() ?? "";
 	if (trimmed === "") return {
 		target: "",
 		kind: "overview",
-		content: renderOverview(namespaces, sandboxEnabled)
+		content: renderOverview(namespaces, sandboxEnabled, externalFailures)
 	};
 	const [maybeNamespace, maybeMethod] = trimmed.includes(".") ? [trimmed.slice(0, trimmed.indexOf(".")), trimmed.slice(trimmed.indexOf(".") + 1)] : [trimmed, void 0];
 	if (sandboxEnabled && maybeNamespace === "sandbox") return {
@@ -77808,29 +77965,29 @@ function createJustBashAdapter() {
 }
 //#endregion
 //#region src/codemode/sandbox/index.ts
-const IDLE_TTL_MS = 900 * 1e3;
-const sessions = /* @__PURE__ */ new Map();
-function armIdleTimer(sessionId) {
-	const session = sessions.get(sessionId);
+const IDLE_TTL_MS$1 = 900 * 1e3;
+const sessions$1 = /* @__PURE__ */ new Map();
+function armIdleTimer$1(sessionId) {
+	const session = sessions$1.get(sessionId);
 	if (!session) return;
 	if (session.timer) clearTimeout(session.timer);
-	session.timer = setTimeout(() => evictSandboxSession(sessionId, "idle-timeout"), IDLE_TTL_MS);
+	session.timer = setTimeout(() => evictSandboxSession(sessionId, "idle-timeout"), IDLE_TTL_MS$1);
 	session.timer.unref?.();
 }
 function getSessionAdapter(sessionId) {
-	let session = sessions.get(sessionId);
+	let session = sessions$1.get(sessionId);
 	if (!session) {
 		session = { adapter: createJustBashAdapter() };
-		sessions.set(sessionId, session);
+		sessions$1.set(sessionId, session);
 	}
-	armIdleTimer(sessionId);
+	armIdleTimer$1(sessionId);
 	return session.adapter;
 }
 function resetSessionAdapter(sessionId) {
-	const session = sessions.get(sessionId);
+	const session = sessions$1.get(sessionId);
 	session?.adapter.dispose?.();
 	if (session) session.adapter = createJustBashAdapter();
-	armIdleTimer(sessionId);
+	armIdleTimer$1(sessionId);
 }
 /**
 * Drop a session's sandbox and its timer. Called by the clean-close (DELETE)
@@ -77839,18 +77996,18 @@ function resetSessionAdapter(sessionId) {
 * @param reason - Why the sandbox is being dropped; included in the eviction log line.
 */
 function evictSandboxSession(sessionId, reason) {
-	const session = sessions.get(sessionId);
+	const session = sessions$1.get(sessionId);
 	if (!session) return;
 	if (session.timer) clearTimeout(session.timer);
 	session.adapter.dispose?.();
-	sessions.delete(sessionId);
+	sessions$1.delete(sessionId);
 	consola.info(`[sandbox] evicted workspace for session ${sessionId} (reason: ${reason})`);
 }
 /**
 * Evict every session (process exit, test cleanup).
 */
 function disposeAllSandboxSessions() {
-	for (const sessionId of [...sessions.keys()]) evictSandboxSession(sessionId, "shutdown");
+	for (const sessionId of [...sessions$1.keys()]) evictSandboxSession(sessionId, "shutdown");
 }
 /**
 * Build the `sandbox` host-module leaf for one codemode run: the full Flue
@@ -77903,6 +78060,414 @@ function buildSandboxApi(sessionId) {
 	};
 }
 //#endregion
+//#region src/utils/mcp-client.ts
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+const REQUEST_TIMEOUT_MS = 3e4;
+var McpHttpClient = class {
+	#url;
+	#fetch;
+	#timeoutMs;
+	#sessionId;
+	#nextId = 1;
+	#initialized;
+	constructor(options) {
+		this.#url = options.url;
+		this.#fetch = options.fetch;
+		this.#timeoutMs = options.timeoutMs ?? REQUEST_TIMEOUT_MS;
+	}
+	/**
+	* Initialize the session (idempotent — concurrent callers share one
+	* handshake). Advertises no client capabilities: no elicitation, no
+	* sampling, no roots.
+	*/
+	initialize() {
+		this.#initialized ??= this.#doInitialize();
+		return this.#initialized;
+	}
+	async #doInitialize() {
+		const result = await this.#request("initialize", {
+			protocolVersion: MCP_PROTOCOL_VERSION,
+			capabilities: {},
+			clientInfo: {
+				name: "mc8yp",
+				version: "0.0.0"
+			}
+		});
+		await this.#notify("notifications/initialized");
+		return {
+			serverName: result?.serverInfo?.name,
+			serverVersion: result?.serverInfo?.version,
+			instructions: result?.instructions
+		};
+	}
+	/**
+	* List every tool, following pagination cursors.
+	*/
+	async listTools() {
+		await this.initialize();
+		const tools = [];
+		let cursor;
+		do {
+			const result = await this.#request("tools/list", cursor ? { cursor } : {});
+			tools.push(...result?.tools ?? []);
+			cursor = result?.nextCursor;
+		} while (cursor);
+		return tools;
+	}
+	/**
+	* Call a tool and unwrap the result: structured content when present,
+	* otherwise joined text content (JSON-parsed when possible). `isError`
+	* results throw with the server's message.
+	* @param name
+	* @param args
+	*/
+	async callTool(name, args) {
+		await this.initialize();
+		const result = await this.#request("tools/call", {
+			name,
+			arguments: args && typeof args === "object" ? args : {}
+		});
+		if (!result || typeof result !== "object") return result;
+		if (result.isError) {
+			const message = (result.content ?? []).filter((c) => c.type === "text").map((c) => c.text ?? "").join("\n") || `MCP tool "${name}" failed`;
+			throw new Error(message);
+		}
+		if (result.structuredContent != null) return result.structuredContent;
+		const content = result.content ?? [];
+		if (content.length === 0 || !content.every((c) => c.type === "text")) return result;
+		const text = content.map((c) => c.text ?? "").join("\n");
+		try {
+			return JSON.parse(text);
+		} catch {
+			return text;
+		}
+	}
+	/**
+	* Best-effort session teardown. Never throws.
+	*/
+	async close() {
+		if (!this.#sessionId) return;
+		try {
+			await this.#fetch(this.#url, {
+				method: "DELETE",
+				headers: { "mcp-session-id": this.#sessionId }
+			});
+		} catch {}
+		this.#sessionId = void 0;
+		this.#initialized = void 0;
+	}
+	async #notify(method) {
+		await this.#post({
+			jsonrpc: "2.0",
+			method
+		});
+	}
+	async #request(method, params) {
+		const id = this.#nextId++;
+		const response = await this.#post({
+			jsonrpc: "2.0",
+			id,
+			method,
+			params
+		});
+		const message = await this.#readResponse(response, id);
+		if (message.error) throw new Error(`MCP ${method} failed: ${message.error.message}`);
+		return message.result;
+	}
+	async #post(payload) {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
+		try {
+			const response = await this.#fetch(this.#url, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					"accept": "application/json, text/event-stream",
+					...this.#sessionId ? { "mcp-session-id": this.#sessionId } : {}
+				},
+				body: JSON.stringify(payload),
+				signal: controller.signal
+			});
+			this.#sessionId ??= response.headers.get("mcp-session-id") ?? void 0;
+			if (!response.ok && response.status !== 202) throw new Error(`MCP endpoint responded with ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`);
+			return response;
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	/**
+	* Read the JSON-RPC response for `id` from a plain-JSON or SSE-framed
+	* response body. Server→client requests encountered on the stream are
+	* declined immediately (fire-and-forget error response) — mc8yp does not
+	* forward elicitation or sampling.
+	* @param response
+	* @param id
+	*/
+	async #readResponse(response, id) {
+		const contentType = response.headers.get("content-type") ?? "";
+		const text = await response.text();
+		const messages = contentType.includes("text/event-stream") ? text.split(/\n\n/).flatMap((event) => event.split("\n").filter((line) => line.startsWith("data: ")).map((line) => line.slice(6))).filter(Boolean).map((data) => JSON.parse(data)) : text.trim() ? [JSON.parse(text)] : [];
+		for (const message of messages) {
+			if (message.method && message.id !== void 0) {
+				this.#declineServerRequest(message).catch(() => void 0);
+				continue;
+			}
+			if (message.id === id) return message;
+		}
+		throw new Error(`MCP endpoint returned no response for request ${id}`);
+	}
+	async #declineServerRequest(request) {
+		consola.warn(`[mcp-client] declining server-initiated request "${request.method}" — mc8yp does not forward elicitation or sampling.`);
+		try {
+			await this.#post({
+				jsonrpc: "2.0",
+				id: request.id,
+				error: {
+					code: -32601,
+					message: `mc8yp does not forward ${request.method === "elicitation/create" ? "elicitation" : request.method === "sampling/createMessage" ? "sampling" : "server-initiated"} requests. The tool cannot interact with the user through this connection.`
+				}
+			});
+		} catch {}
+	}
+};
+//#endregion
+//#region src/utils/external-mcp.ts
+const NAMESPACE_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+* Parse external MCP server entries from header values or CLI flags. Every
+* entry is a JSON object `{ name, url, token?, headers?, description? }`, or a
+* JSON array of them.
+*
+* Validation is strict and fail-loud rather than skip-and-continue: a
+* malformed entry means the operator intended a server the agent would
+* otherwise silently not have, so callers turn `failedEntries` into a 400
+* (server mode) or a startup error (CLI).
+* @param sources Raw JSON texts, one per entry.
+*/
+function parseExternalMcpServers(sources) {
+	const servers = [];
+	const failedEntries = [];
+	const usedNames = /* @__PURE__ */ new Set();
+	for (const source of sources) {
+		let parsed;
+		try {
+			parsed = JSON.parse(source);
+		} catch (err) {
+			failedEntries.push({
+				entry: source,
+				reason: `Not valid JSON (${err instanceof Error ? err.message : String(err)}). Expected {"name":"…","url":"https://…","token":"…"}.`
+			});
+			continue;
+		}
+		for (const candidate of Array.isArray(parsed) ? parsed : [parsed]) {
+			const result = validateExternalMcpEntry(candidate, usedNames);
+			if ("reason" in result) {
+				failedEntries.push({
+					entry: typeof candidate === "object" ? JSON.stringify(candidate) : String(candidate),
+					reason: result.reason
+				});
+				continue;
+			}
+			usedNames.add(result.config.name);
+			servers.push(result.config);
+		}
+	}
+	return {
+		servers,
+		failedEntries
+	};
+}
+/**
+* Validate one entry, exported so the resolve route can answer with the exact
+* verdict the header path would reach — a route that green-lights a server the
+* header then rejects is worse than no route at all.
+* @param candidate Parsed JSON entry.
+* @param usedNames Namespaces already taken by earlier entries in the same batch.
+*/
+function validateExternalMcpEntry(candidate, usedNames) {
+	if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) return { reason: "Entry must be a JSON object with \"name\" and \"url\"." };
+	const entry = candidate;
+	if (typeof entry.name !== "string" || entry.name === "") return { reason: "\"name\" is required and must be a non-empty string — it becomes the sandbox namespace." };
+	if (!NAMESPACE_PATTERN.test(entry.name)) return { reason: `"name" must be a valid JavaScript identifier (letters, digits, underscore; not starting with a digit), got "${entry.name}".` };
+	if (RESERVED_NAMESPACES.has(entry.name)) return { reason: `"name" must not be a reserved namespace (${[...RESERVED_NAMESPACES].join(", ")}), got "${entry.name}".` };
+	if (usedNames.has(entry.name)) return { reason: `Duplicate namespace "${entry.name}" — each external MCP server needs its own name.` };
+	if (typeof entry.url !== "string" || entry.url === "") return { reason: `"url" is required and must be a non-empty string (server "${entry.name}").` };
+	let url;
+	try {
+		url = new URL(entry.url);
+	} catch {
+		return { reason: `"url" must be an absolute URL, got "${entry.url}" (server "${entry.name}").` };
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return { reason: `"url" must use http or https, got "${url.protocol}" (server "${entry.name}").` };
+	if (entry.token !== void 0 && (typeof entry.token !== "string" || entry.token === "")) return { reason: `"token" must be a non-empty string when present (server "${entry.name}").` };
+	if (entry.description !== void 0 && typeof entry.description !== "string") return { reason: `"description" must be a string when present (server "${entry.name}").` };
+	let headers;
+	if (entry.headers !== void 0) {
+		if (typeof entry.headers !== "object" || entry.headers === null || Array.isArray(entry.headers)) return { reason: `"headers" must be an object of string values when present (server "${entry.name}").` };
+		headers = {};
+		for (const [key, value] of Object.entries(entry.headers)) {
+			if (typeof value !== "string") return { reason: `"headers.${key}" must be a string (server "${entry.name}").` };
+			headers[key] = value;
+		}
+	}
+	return { config: {
+		name: entry.name,
+		url: entry.url,
+		...typeof entry.token === "string" ? { token: entry.token } : {},
+		...headers ? { headers } : {},
+		...typeof entry.description === "string" ? { description: entry.description } : {}
+	} };
+}
+/**
+* Request headers for one external server: the `token` bearer shorthand,
+* then the explicit `headers` map so it can override.
+* @param config External server config.
+*/
+function externalMcpHeaders(config) {
+	return {
+		...config.token ? { authorization: `Bearer ${config.token}` } : {},
+		...config.headers
+	};
+}
+/**
+* Transport for an external MCP server: plain `fetch` against the absolute
+* URL with the entry's own credentials attached. No tenant auth, no safeFetch
+* host pinning — the target is an arbitrary operator-chosen host, not the
+* tenant.
+* @param config External server config.
+*/
+function createExternalMcpFetch(config) {
+	const authHeaders = externalMcpHeaders(config);
+	return (url, init) => fetch(url, {
+		...init,
+		headers: {
+			...init.headers,
+			...authHeaders
+		}
+	});
+}
+//#endregion
+//#region src/codemode/external-mcp-session.ts
+const IDLE_TTL_MS = 900 * 1e3;
+const sessions = /* @__PURE__ */ new Map();
+function configKey(config) {
+	return JSON.stringify([
+		config.name,
+		config.url,
+		config.token ?? "",
+		config.headers ?? {}
+	]);
+}
+function armIdleTimer(sessionKey) {
+	const session = sessions.get(sessionKey);
+	if (!session) return;
+	if (session.timer) clearTimeout(session.timer);
+	session.timer = setTimeout(() => evictExternalMcpSession(sessionKey, "idle-timeout"), IDLE_TTL_MS);
+	session.timer.unref?.();
+}
+/**
+* Handshake one external server and read its tool list, bypassing the session
+* cache entirely.
+*
+* Exported for configuration checks (`POST /resolve-mcp-servers`): an operator
+* asking "does this URL and token work" must not be answered from a tool list
+* cached up to 15 minutes ago, and a candidate that may never be saved must not
+* seed the cache either. Runtime resolution goes through
+* {@link resolveExternalMcpServers}, which is where caching belongs.
+* @param config One external server config.
+*/
+async function probeExternalMcpServer(config) {
+	const client = new McpHttpClient({
+		url: config.url,
+		fetch: createExternalMcpFetch(config)
+	});
+	try {
+		const info = await client.initialize();
+		const tools = await client.listTools();
+		consola.info(`[external-mcp] "${config.name}" at ${config.url}: ${tools.length} tool(s)`);
+		return {
+			config,
+			tools,
+			instructions: info.instructions,
+			serverName: info.serverName,
+			serverVersion: info.serverVersion
+		};
+	} finally {
+		await client.close();
+	}
+}
+/**
+* Resolve every configured external MCP server for a session, using the cached
+* tool list where one exists. Servers whose handshake fails are reported in
+* `failures` and get no namespace — mirroring how a discovered service with a
+* failed spec download is skipped, except that these were explicitly requested
+* so the agent is told about them.
+* @param sessionKey MCP session id, or {@link CLI_EXTERNAL_MCP_SESSION} in CLI mode.
+* @param configs Parsed connection config.
+*/
+async function resolveExternalMcpServers(sessionKey, configs) {
+	if (configs.length === 0) return {
+		servers: [],
+		failures: []
+	};
+	let session = sessions.get(sessionKey);
+	if (!session) {
+		session = { servers: /* @__PURE__ */ new Map() };
+		sessions.set(sessionKey, session);
+	}
+	armIdleTimer(sessionKey);
+	const settled = await Promise.all(configs.map(async (config) => {
+		const key = configKey(config);
+		let pending = session.servers.get(key);
+		if (!pending) {
+			pending = probeExternalMcpServer(config);
+			session.servers.set(key, pending);
+			pending.catch(() => {
+				if (session.servers.get(key) === pending) session.servers.delete(key);
+			});
+		}
+		try {
+			return {
+				ok: true,
+				server: await pending
+			};
+		} catch (err) {
+			const reason = err instanceof Error ? err.message : String(err);
+			consola.warn(`[external-mcp] "${config.name}" at ${config.url} unavailable:`, reason);
+			return {
+				ok: false,
+				failure: {
+					name: config.name,
+					url: config.url,
+					reason
+				}
+			};
+		}
+	}));
+	return {
+		servers: settled.flatMap((r) => r.ok ? [r.server] : []),
+		failures: settled.flatMap((r) => r.ok ? [] : [r.failure])
+	};
+}
+/**
+* Drop a session's cached external tool lists and its timer.
+* @param sessionKey MCP session id (or the CLI key).
+* @param reason Why the entry is being dropped; included in the log line.
+*/
+function evictExternalMcpSession(sessionKey, reason) {
+	const session = sessions.get(sessionKey);
+	if (!session) return;
+	if (session.timer) clearTimeout(session.timer);
+	sessions.delete(sessionKey);
+	consola.info(`[external-mcp] dropped cached tool lists for session ${sessionKey} (reason: ${reason})`);
+}
+/**
+* Evict every session (process exit, test cleanup).
+*/
+function disposeAllExternalMcpSessions() {
+	for (const sessionKey of [...sessions.keys()]) evictExternalMcpSession(sessionKey, "shutdown");
+}
+//#endregion
 //#region node_modules/.pnpm/tslib@2.8.1/node_modules/tslib/tslib.es6.mjs
 function __awaiter(thisArg, _arguments, P, generator) {
 	function adopt(value) {
@@ -134718,177 +135283,6 @@ function createC8yAuthHeaders(auth) {
 	throw new Error("Invalid authentication credentials");
 }
 //#endregion
-//#region src/utils/mcp-client.ts
-const MCP_PROTOCOL_VERSION = "2025-06-18";
-const REQUEST_TIMEOUT_MS = 3e4;
-var McpHttpClient = class {
-	#url;
-	#fetch;
-	#timeoutMs;
-	#sessionId;
-	#nextId = 1;
-	#initialized;
-	constructor(options) {
-		this.#url = options.url;
-		this.#fetch = options.fetch;
-		this.#timeoutMs = options.timeoutMs ?? REQUEST_TIMEOUT_MS;
-	}
-	/**
-	* Initialize the session (idempotent — concurrent callers share one
-	* handshake). Advertises no client capabilities: no elicitation, no
-	* sampling, no roots.
-	*/
-	initialize() {
-		this.#initialized ??= this.#doInitialize();
-		return this.#initialized;
-	}
-	async #doInitialize() {
-		const result = await this.#request("initialize", {
-			protocolVersion: MCP_PROTOCOL_VERSION,
-			capabilities: {},
-			clientInfo: {
-				name: "mc8yp",
-				version: "0.0.0"
-			}
-		});
-		await this.#notify("notifications/initialized");
-		return {
-			serverName: result?.serverInfo?.name,
-			serverVersion: result?.serverInfo?.version,
-			instructions: result?.instructions
-		};
-	}
-	/**
-	* List every tool, following pagination cursors.
-	*/
-	async listTools() {
-		await this.initialize();
-		const tools = [];
-		let cursor;
-		do {
-			const result = await this.#request("tools/list", cursor ? { cursor } : {});
-			tools.push(...result?.tools ?? []);
-			cursor = result?.nextCursor;
-		} while (cursor);
-		return tools;
-	}
-	/**
-	* Call a tool and unwrap the result: structured content when present,
-	* otherwise joined text content (JSON-parsed when possible). `isError`
-	* results throw with the server's message.
-	* @param name
-	* @param args
-	*/
-	async callTool(name, args) {
-		await this.initialize();
-		const result = await this.#request("tools/call", {
-			name,
-			arguments: args && typeof args === "object" ? args : {}
-		});
-		if (!result || typeof result !== "object") return result;
-		if (result.isError) {
-			const message = (result.content ?? []).filter((c) => c.type === "text").map((c) => c.text ?? "").join("\n") || `MCP tool "${name}" failed`;
-			throw new Error(message);
-		}
-		if (result.structuredContent != null) return result.structuredContent;
-		const content = result.content ?? [];
-		if (content.length === 0 || !content.every((c) => c.type === "text")) return result;
-		const text = content.map((c) => c.text ?? "").join("\n");
-		try {
-			return JSON.parse(text);
-		} catch {
-			return text;
-		}
-	}
-	/**
-	* Best-effort session teardown. Never throws.
-	*/
-	async close() {
-		if (!this.#sessionId) return;
-		try {
-			await this.#fetch(this.#url, {
-				method: "DELETE",
-				headers: { "mcp-session-id": this.#sessionId }
-			});
-		} catch {}
-		this.#sessionId = void 0;
-		this.#initialized = void 0;
-	}
-	async #notify(method) {
-		await this.#post({
-			jsonrpc: "2.0",
-			method
-		});
-	}
-	async #request(method, params) {
-		const id = this.#nextId++;
-		const response = await this.#post({
-			jsonrpc: "2.0",
-			id,
-			method,
-			params
-		});
-		const message = await this.#readResponse(response, id);
-		if (message.error) throw new Error(`MCP ${method} failed: ${message.error.message}`);
-		return message.result;
-	}
-	async #post(payload) {
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
-		try {
-			const response = await this.#fetch(this.#url, {
-				method: "POST",
-				headers: {
-					"content-type": "application/json",
-					"accept": "application/json, text/event-stream",
-					...this.#sessionId ? { "mcp-session-id": this.#sessionId } : {}
-				},
-				body: JSON.stringify(payload),
-				signal: controller.signal
-			});
-			this.#sessionId ??= response.headers.get("mcp-session-id") ?? void 0;
-			if (!response.ok && response.status !== 202) throw new Error(`MCP endpoint responded with ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`);
-			return response;
-		} finally {
-			clearTimeout(timer);
-		}
-	}
-	/**
-	* Read the JSON-RPC response for `id` from a plain-JSON or SSE-framed
-	* response body. Server→client requests encountered on the stream are
-	* declined immediately (fire-and-forget error response) — mc8yp does not
-	* forward elicitation or sampling.
-	* @param response
-	* @param id
-	*/
-	async #readResponse(response, id) {
-		const contentType = response.headers.get("content-type") ?? "";
-		const text = await response.text();
-		const messages = contentType.includes("text/event-stream") ? text.split(/\n\n/).flatMap((event) => event.split("\n").filter((line) => line.startsWith("data: ")).map((line) => line.slice(6))).filter(Boolean).map((data) => JSON.parse(data)) : text.trim() ? [JSON.parse(text)] : [];
-		for (const message of messages) {
-			if (message.method && message.id !== void 0) {
-				this.#declineServerRequest(message).catch(() => void 0);
-				continue;
-			}
-			if (message.id === id) return message;
-		}
-		throw new Error(`MCP endpoint returned no response for request ${id}`);
-	}
-	async #declineServerRequest(request) {
-		consola.warn(`[mcp-client] declining server-initiated request "${request.method}" — mc8yp does not forward elicitation or sampling.`);
-		try {
-			await this.#post({
-				jsonrpc: "2.0",
-				id: request.id,
-				error: {
-					code: -32601,
-					message: `mc8yp does not forward ${request.method === "elicitation/create" ? "elicitation" : request.method === "sampling/createMessage" ? "sampling" : "server-initiated"} requests. The tool cannot interact with the user through this connection.`
-				}
-			});
-		} catch {}
-	}
-};
-//#endregion
 //#region src/codemode/execute.ts
 const EXECUTE_ENTRY_PATH = "/codemode-execute.mjs";
 const BLOCKED_REQUEST_PREFIX = "Request blocked by MCP connection policy.";
@@ -134905,6 +135299,7 @@ async function getSandbox() {
 }
 process$1.once("exit", () => {
 	disposeAllSandboxSessions();
+	disposeAllExternalMcpSessions();
 	if (sandboxPromise) sandboxPromise.then((s) => s.dispose()).catch(() => void 0);
 });
 function formatRestrictionBlockMessage(method, pathname, matching) {
@@ -135030,29 +135425,39 @@ function buildAgentModule(functionCode) {
 		"export default __mc8ypExecute"
 	].join("\n");
 }
-function createLiveCalls(safeFetch, tenantUrl, authHeaders) {
+function createLiveCalls(tenant) {
 	const mcpClients = /* @__PURE__ */ new Map();
-	const base = tenantUrl.endsWith("/") ? tenantUrl : `${tenantUrl}/`;
 	const mcpClientFor = (namespace) => {
 		let client = mcpClients.get(namespace.name);
 		if (!client) {
-			client = new McpHttpClient({
-				url: namespace.server.url,
-				fetch: (path, init) => fetch(new URL(path.replace(/^\//, ""), base), {
-					...init,
-					headers: {
-						...init.headers,
-						...namespace.server.sendAuthentication ? authHeaders : {}
-					}
-				})
+			if (namespace.external) client = new McpHttpClient({
+				url: namespace.external.url,
+				fetch: createExternalMcpFetch(namespace.external)
 			});
+			else {
+				if ("error" in tenant) throw new Error(tenant.error);
+				const { tenantUrl, authHeaders } = tenant;
+				const base = tenantUrl.endsWith("/") ? tenantUrl : `${tenantUrl}/`;
+				client = new McpHttpClient({
+					url: namespace.server.url,
+					fetch: (path, init) => fetch(new URL(path.replace(/^\//, ""), base), {
+						...init,
+						headers: {
+							...init.headers,
+							...namespace.server.sendAuthentication ? authHeaders : {}
+						}
+					})
+				});
+			}
 			mcpClients.set(namespace.name, client);
 		}
 		return client;
 	};
 	return {
 		operation: async (namespace, opName, input) => {
-			return performRequest(safeFetch, tenantUrl, toRequest(namespace.operations.find((o) => o.name === opName), input));
+			if ("error" in tenant) throw new Error(tenant.error);
+			const op = namespace.operations.find((o) => o.name === opName);
+			return performRequest(tenant.safeFetch, tenant.tenantUrl, toRequest(op, input));
 		},
 		mcpCall: async (namespace, toolName, args) => {
 			return mcpClientFor(namespace).callTool(toolName, args);
@@ -135063,17 +135468,7 @@ function createLiveCalls(safeFetch, tenantUrl, authHeaders) {
 		}
 	};
 }
-function createUnauthenticatedCalls(message) {
-	const fail = async () => {
-		throw new Error(message);
-	};
-	return {
-		operation: fail,
-		mcpCall: fail,
-		dispose: async () => {}
-	};
-}
-function buildApiModule(namespaces, methodIndex, docsIndex, live, sandbox) {
+function buildApiModule(namespaces, methodIndex, docsIndex, live, sandbox, externalFailures) {
 	const visibleTargets = new Set(namespaces.flatMap((ns) => ns.kind === "openapi" ? ns.operations.map((op) => `${ns.name}.${op.name}`) : ns.tools.map((tool) => `${ns.name}.${tool.name}`)));
 	const sandboxEnabled = sandbox !== void 0;
 	return {
@@ -135090,9 +135485,15 @@ function buildApiModule(namespaces, methodIndex, docsIndex, live, sandbox) {
 					const targets = target.filter((t) => typeof t === "string" && t.trim() !== "");
 					if (targets.length === 0) throw new TypeError("codemode.describe(targets): pass method targets like \"c8y.getAlarmCollectionResource\"");
 					if (targets.length > 5) throw new TypeError(`codemode.describe(targets): at most 5 targets per call (got ${targets.length}) — shortlist candidates via search first`);
-					return targets.map((t) => describeTarget(namespaces, methodIndex, t, sandboxEnabled));
+					return targets.map((t) => describeTarget(namespaces, methodIndex, t, {
+						sandboxEnabled,
+						externalFailures
+					}));
 				}
-				return describeTarget(namespaces, methodIndex, target == null ? void 0 : String(target), sandboxEnabled);
+				return describeTarget(namespaces, methodIndex, target == null ? void 0 : String(target), {
+					sandboxEnabled,
+					externalFailures
+				});
 			}
 		},
 		docs: {
@@ -135110,18 +135511,28 @@ function buildApiModule(namespaces, methodIndex, docsIndex, live, sandbox) {
 		namespaces: Object.fromEntries(namespaces.map((namespace) => [namespace.name, namespace.kind === "openapi" ? Object.fromEntries(namespace.operations.map((op) => [op.name, async (...args) => live.operation(namespace, op.name, args[0])])) : Object.fromEntries(namespace.tools.map((tool) => [tool.name, async (...args) => live.mcpCall(namespace, tool.toolName, args[0])]))]))
 	};
 }
-function resolveRuntime() {
+async function resolveRuntime() {
 	const custom = c8yMcpServer.ctx.custom;
 	const resolved = custom?.specs;
 	if (!resolved) throw new Error(custom?.env === "cli" ? "No active tenant set. Call set-active-tenant first." : "No tenant specs available for this MCP connection. This usually means the request reached the server without a resolvable tenant context (e.g. a platform probe). Reconnect with valid tenant auth.");
 	const restrictions = custom?.restrictions ?? [];
 	const allowRules = custom?.allowRules ?? [];
 	const noMcp = custom?.noMcp;
+	const { servers: externalServers, failures: externalFailures } = await resolveExternalMcpServers(c8yMcpServer.ctx.sessionId ?? "cli", custom?.externalMcpServers ?? []);
+	const namespaces = buildNamespaces(resolved, {
+		restrictions,
+		allowRules,
+		noMcp,
+		externalServers
+	});
+	const externalNames = new Set(namespaces.filter((ns) => ns.kind === "mcp" && ns.external).map((ns) => ns.name));
 	return {
 		resolved,
 		restrictions,
 		allowRules,
-		namespaces: buildNamespaces(resolved, restrictions, allowRules, noMcp)
+		namespaces,
+		externalFailures,
+		externalMethods: toSearchableMethods(namespaces.filter((ns) => externalNames.has(ns.name)))
 	};
 }
 const NO_DEFAULT_EXPORT_MESSAGE = "Execution completed without returning a value.";
@@ -135137,29 +135548,34 @@ function withCliTenantMarker(text, tenantUrl) {
 	return `${tenantUrl ? `Executed against tenant: ${tenantUrl}` : "No active tenant — discovery only. Live API calls require set-active-tenant, and visible specs are bundled reference snapshots that may not exist on any tenant."}\n\n${text}`;
 }
 async function execute(functionCode) {
-	const { resolved, namespaces, restrictions, allowRules } = resolveRuntime();
+	const { resolved, namespaces, restrictions, allowRules, externalFailures, externalMethods } = await resolveRuntime();
 	const SPEC_VIEW = {
 		all: true,
 		contextPaths: /* @__PURE__ */ new Set()
 	};
-	const docsIndex = getDocsIndex(resolved, () => buildNamespaces(resolved, [], [], SPEC_VIEW).filter((ns) => ns.kind === "openapi").map((ns) => ({
+	const docsIndex = getDocsIndex(resolved, () => buildNamespaces(resolved, { noMcp: SPEC_VIEW }).filter((ns) => ns.kind === "openapi").map((ns) => ({
 		namespace: ns.name,
 		spec: ns.spec
 	})));
-	const methodIndex = getMethodIndex(resolved, () => {
+	const tenantMethodIndex = getMethodIndex(resolved, () => {
 		const byTarget = /* @__PURE__ */ new Map();
-		for (const item of [...toSearchableMethods(buildNamespaces(resolved)), ...toSearchableMethods(buildNamespaces(resolved, [], [], SPEC_VIEW))]) byTarget.set(item.target, item);
+		for (const item of [...toSearchableMethods(buildNamespaces(resolved)), ...toSearchableMethods(buildNamespaces(resolved, { noMcp: SPEC_VIEW }))]) byTarget.set(item.target, item);
 		return [...byTarget.values()];
 	});
+	const methodIndex = externalMethods.length === 0 ? tenantMethodIndex : buildMethodIndex([...tenantMethodIndex.methods.values(), ...externalMethods]);
 	let tenantUrl = null;
 	let live;
 	try {
 		const auth = await resolveC8yAuth();
 		tenantUrl = auth.tenantUrl;
 		const authHeaders = createC8yAuthHeaders(auth);
-		live = createLiveCalls(createCumulocitySafeFetch(auth.tenantUrl, authHeaders, restrictions, allowRules), auth.tenantUrl, authHeaders);
+		live = createLiveCalls({
+			safeFetch: createCumulocitySafeFetch(auth.tenantUrl, authHeaders, restrictions, allowRules),
+			tenantUrl: auth.tenantUrl,
+			authHeaders
+		});
 	} catch (error) {
-		live = createUnauthenticatedCalls(error instanceof Error ? error.message : String(error));
+		live = createLiveCalls({ error: error instanceof Error ? error.message : String(error) });
 	}
 	const sessionId = c8yMcpServer.ctx.sessionId;
 	const sandboxApi = c8yMcpServer.ctx.custom?.env === "server" && sessionId && c8yMcpServer.ctx.custom?.enableSandbox ? buildSandboxApi(sessionId) : void 0;
@@ -135168,7 +135584,7 @@ async function execute(functionCode) {
 		filename: EXECUTE_ENTRY_PATH,
 		limits: SANDBOX_LIMITS,
 		imports: {
-			[API_MODULE_SPECIFIER]: buildApiModule(namespaces, methodIndex, docsIndex, live, sandboxApi),
+			[API_MODULE_SPECIFIER]: buildApiModule(namespaces, methodIndex, docsIndex, live, sandboxApi, externalFailures),
 			[AGENT_MODULE_SPECIFIER]: buildAgentModule(functionCode)
 		}
 	}).finally(() => live.dispose());
@@ -135255,10 +135671,11 @@ declare const docs: {
 }
 
 // API namespaces: \`c8y\` (Cumulocity core — always present) plus one global
-// per microservice available on the current tenant (e.g. \`dtm\`), each with
-// one typed method per operation. If a method seems missing, search
-// with different wording; if it truly does not exist, say so instead of
-// improvising:
+// per microservice available on the current tenant (e.g. \`dtm\`), plus any
+// external MCP server configured for this connection — each with one typed
+// method per operation. \`codemode.describe()\` lists what this connection
+// actually has. If a method seems missing, search with different wording; if
+// it truly does not exist, say so instead of improvising:
 //   await c8y.getManagedObjectCollectionResource({ pageSize: 5 })
 \`\`\`
 
@@ -140737,17 +141154,17 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 		"openapi": "3.0.1",
 		"info": {
 			"title": "DTM Asset and Definition API",
-			"description": "The Digital Twin Manager (DTM) enables schema-based modeling in Cumulocity.\nIt allows creating and managing data model schemas, which serve as blueprints for all Cumulocity domain model entities such as assets and their properties, but also, for example, events, alarms, and measurements.\nThese blueprints act as reusable templates within the platform and are used to describe the logical structure, hierarchies and constraints of\ncomplex [business assets](https://cumulocity.com/docs/glossary/#assets) also known as [digital twins](https://cumulocity.com/docs/glossary/#digital-twin).\n\nThe DTM API is the interface to manage the schema definitions as well as the (asset) instances based on these definitions. The API is structured to separate schema governance (Definition API) from instance management (Asset API):\n\nThe **Definition API** provides the governance layer of the DTM to manage the reusable schema elements that define the structure used to describe, create or validate schema for domain model entities, called _definitions_. \n\nThe **Asset API** allows managing asset instances based on predefined Asset Definitions (also known as [Asset Models](https://cumulocity.com/docs/glossary/#asset-models)). Asset instances created from an Asset Model inherit the structure and constraints defined in the model.\n\n# Cumulocity REST API\n\nThe DTM Definition API and Asset API are an extension of the Cumulocity REST API and follow the same design principles and aspects common to all REST-based interfaces of Cumulocity. For general information about the Cumulocity REST API, see the [Cumulocity REST API documentation](https://cumulocity.com/api/core/).\n\n# Authorization\n\nAll requests issued to DTM Definition API and Asset API are subject to authentication and authorization. For detailed information about authentication, refer to the Cumulocity Core OpenAPI specification details on [Authentication](https://cumulocity.com/api/core/#section/Authentication). To determine the required permissions, see the \"Required user role\" entries for the individual requests.\n\nFor general information about permissions and the concept of ownership in Cumulocity, see [Getting started > Technical concepts > Security aspects > Access control > Managing roles and assigning permissions](https://www.cumulocity.com/docs/concepts/security/#managing-roles-and-assigning-permissions) in the [Cumulocity user documentation](https://cumulocity.com/docs/).\n<br>",
+			"description": "The Digital Twin Manager (DTM) enables schema-based modeling in Cumulocity.\nIt allows creating and managing data model schemas, which serve as blueprints for all Cumulocity domain model entities such as assets and their properties, but also, for example, events, alarms, and measurements.\nThese blueprints act as reusable templates within the platform and are used to describe the logical structure, hierarchies and constraints of complex [business assets](https://cumulocity.com/docs/glossary/#assets) also known as [digital twins]\n(https://cumulocity.com/docs/glossary/#digital-twin).\n\nThe DTM API is the interface to manage the schema definitions as well as the (asset) instances based on these definitions. The API is structured to separate schema governance (Definition API) from instance management (Asset API):\n\n### Definition API\n\nThe **Definition API** provides the governance layer of the DTM to manage the reusable schema elements that define the structure used to describe, create or validate schema for domain model entities, called _definitions_.\nBy default, the definitions are maintained on each tenant individually, but they can also be shared across tenants in a Cumulocity multi-tenant environment. To achieve that, the tenant option `definitions.multitenant.sharing.mode` needs to be set\nto `enabled` on the enterprise tenant and the subtenants. When sharing is enabled, the definitions can be created and updated only in the enterprise tenant. The subtenants will have read-only access to the shared definitions.\n\n### Asset API\n\nThe **Asset API** allows managing asset instances based on predefined Asset Definitions (also known as [Asset Models](https://cumulocity.com/docs/glossary/#asset-models)). Asset instances created from an Asset Model inherit the structure and\nconstraints defined in the model.\n\n# Cumulocity REST API\n\nThe DTM Definition API and Asset API are an extension of the Cumulocity REST API and follow the same design principles and aspects common to all REST-based interfaces of Cumulocity. For general information about the Cumulocity REST API, see the\n[Cumulocity REST API documentation](https://cumulocity.com/api/core/).\n\n# Authorization\n\nAll requests issued to DTM Definition API and Asset API are subject to authentication and authorization. For detailed information about authentication, refer to the Cumulocity Core OpenAPI specification details on [Authentication]\n(https://cumulocity.com/api/core/#section/Authentication). To determine the required permissions, see the \"Required user role\" entries for the individual requests.\n\nFor general information about permissions and the concept of ownership in Cumulocity,\nsee [Getting started > Technical concepts > Security aspects > Access control > Managing roles and assigning permissions](https://www.cumulocity.com/docs/concepts/security/#managing-roles-and-assigning-permissions) in\nthe [Cumulocity user documentation](https://cumulocity.com/docs/).\n<br>\n# Accessing the DTM API\n**Info:** The URL paths of proxied requests consist of:\n* the path of the microservice, which you will find in the application properties of the microservice\n* the corresponding DTM REST API path.\n\n**Example:** For the system `eu-latest.cumulocity.com` and tenant domain name `dtm-demo`, the base URL would be `https://dtm-demo.eu-latest.cumulocity.com/service/dtm/`. The endpoint to query assets is `/assets`. Thus, the complete endpoint path is `https://dtm-demo.eu-latest.cumulocity.com/service/dtm/assets`.\n",
 			"version": "Latest"
 		},
 		"servers": [{
-			"url": "https://<TENANT_DOMAIN>",
+			"url": "/",
 			"description": "The Digital Twin Manager service."
 		}],
 		"tags": [
 			{
 				"name": "Assets",
-				"description": "The Asset API extends the Cumulocity core capabilities and domain model to manage assets with schema-based governance by linking asset instances to predefined Asset Definitions (also known as Asset Models). The Asset Definition serves as a blueprint\nfor the asset instances, defining\ntheir structure and constraints and relationships within an asset hierarchy.\n\nAsset instances without a linked Asset Definition are treated as generic assets without schema governance or constraints of the logical structure defined in an Asset Definition.\n\nThe Asset API extends the Cumulocity core capabilities with\n* Schema Governance: Enforcing and managing the underlying data schemas.\n* Integration: Synchronizing external sources of assets and digital twins.\n* Bulk Operations: Facilitating large-scale asset management.\n* Linked Series: Linking of time-series context to assets.\n* Permissions: Elevated permissions for synchronization and linked series management.\n\n### Asset Synchronization\n\nThe Asset API provides optimized operations specifically designed to efficiently create or update assets within synchronization workflows from external systems.\n\nFor referencing an asset from an external system, a unique identifier is required to map the asset between Cumulocity and the external system. This unique identifier is used in addition to the Cumulocity asset id and can be used to query the asset via the Asset API. This has a significant performance benefit over using any custom fragment property or even properties to identify the asset. Internally the Asset API creates an external id in the Identity API of type `c8y_Asset` for each asset that has an external identifier set via the `c8y_ExternalId` fragment.\n\nUsing the external identifier, the Asset API can perform idempotent create or update operations. This means that if an asset with the specified external identifier already exists, it will be updated; otherwise, a new asset will be created. This is particularly useful in synchronization scenarios where the same asset data may be processed multiple times, ensuring that duplicate assets are not created.\n\nIf the asset has the `c8y_ExternalAsset` fragment, it is considered to be externally managed applying additional restrictions on update and delete operations to avoid unintended modifications of externally managed assets. See the Permissions section below for more details.\n\nThe `c8y_ExternalAsset` fragment allows defining a `source` to indicate the origin of the external asset.\n\n```json\n{\n  \"c8y_ExternalAsset\": {\n    \"source\": \"string\"\n  }\n}\n```\n\n### Permissions\n\nBy default, for all Asset API operations, users require the corresponding *ROLE_INVENTORY_\\** permission to create, update or delete assets. The *ROLE_DIGITAL_TWIN_ASSETS_\\** permissions are elevated permissions that are specifically designed to control modifications of externally managed assets in addition to the *ROLE_INVENTORY_\\** roles and permissions.\n\nThe *ROLE_DIGITAL_TWIN_ASSETS_\\** permissions are only required for updating or deleting externally managed assets (assets having the `c8y_ExternalAsset` fragment).\nThis is especially useful for using the Asset API for synchronization of assets from an external source and to control modifications of these externally managed assets within Cumulocity while still allowing regular\n(not external) assets to be managed without additional permissions.\n\nTo enforce always requiring the *ROLE_DIGITAL_TWIN_ASSETS_\\** permissions, no matter if the asset is external or not, the tenant option `assets.permission.mode` can be configured to `all`. In this case, the *ROLE_DIGITAL_TWIN_ASSETS_CREATE* permission is required to create assets. To disable the requirement of *ROLE_DIGITAL_TWIN_ASSETS_\\** permissions completely, the tenant option can be set to `none`.\n\nThe following elevated permissions are available for the Asset API:\n\n- *ROLE_DIGITAL_TWIN_ASSETS_CREATE*: Users can create new assets including LinkedSeries and their Source.\n- *ROLE_DIGITAL_TWIN_ASSETS_UPDATE*: Users can update existing assets including LinkedSeries and their Source.\n- *ROLE_DIGITAL_TWIN_ASSETS_ADMIN*: Users can manage all assets, including creating, updating, and deleting them.\n"
+				"description": "The Asset API extends the Cumulocity core capabilities and domain model to manage assets with schema-based governance by linking asset instances to predefined Asset Definitions (also known as Asset Models). The Asset Definition serves as a blueprint\nfor the asset instances, defining\ntheir structure and constraints and relationships within an asset hierarchy.\n\nAsset instances without a linked Asset Definition are treated as generic assets without schema governance or constraints of the logical structure defined in an Asset Definition.\n\nThe Asset API extends the Cumulocity core capabilities with\n* Schema Governance: Enforcing and managing the underlying data schemas.\n* Integration: Synchronizing external sources of assets and digital twins.\n* Bulk Operations: Facilitating large-scale asset management.\n* Linked Series: Linking of time-series context to assets.\n* Permissions: Elevated permissions for synchronization and linked series management.\n\n### Asset Synchronization\n\nThe Asset API provides optimized operations specifically designed to efficiently create or update assets within synchronization workflows from external systems.\n\nFor referencing an asset from an external system, a unique identifier is required to map the asset between Cumulocity and the external system. This unique identifier is used in addition to the Cumulocity asset id and can be used to query the asset via the Asset API. This has a significant performance benefit over using any custom fragment property or even properties to identify the asset. Internally the Asset API creates an external id in the Identity API of type `c8y_Asset` for each asset that has an external identifier set via the `c8y_ExternalId` fragment.\n\nUsing the external identifier, the Asset API can perform idempotent create or update operations. This means that if an asset with the specified external identifier already exists, it will be updated; otherwise, a new asset will be created. This is particularly useful in synchronization scenarios where the same asset data may be processed multiple times, ensuring that duplicate assets are not created.\n\nIf the asset has the `c8y_ExternalAsset` fragment, it is considered to be externally managed applying additional restrictions on update and delete operations to avoid unintended modifications of externally managed assets. See the Permissions section below for more details.\n\nThe `c8y_ExternalAsset` fragment allows defining a `source` to indicate the origin of the external asset.\n\n```json\n{\n  \"c8y_ExternalAsset\": {\n    \"source\": \"string\"\n  }\n}\n```\n\n### Permissions\n\nBy default, for all Asset API operations, users require the corresponding *ROLE_INVENTORY_\\** permission to create, update or delete assets. The *ROLE_DIGITAL_TWIN_ASSETS_\\** permissions are elevated permissions that are specifically designed to control modifications of externally managed assets in addition to the *ROLE_INVENTORY_\\** roles and permissions.\n\nBy default, the *ROLE_DIGITAL_TWIN_ASSETS_\\** permissions are only required for updating (including assigning devices) or deleting externally managed assets (assets having the `c8y_ExternalAsset` fragment).\nThis is especially useful for using the Asset API for synchronization of assets from an external source and to control modifications of these externally managed assets within Cumulocity while still allowing regular\n(not external) assets to be managed without additional permissions.\n\nThis behavior can be configured by setting the tenant option `assets.permission.mode`: to enforce **always** requiring the *ROLE_DIGITAL_TWIN_ASSETS_\\** permissions, no matter if the asset is external or not, the tenant option can be configured to\n`all`. In this case, the *ROLE_DIGITAL_TWIN_ASSETS_CREATE* permission is required to create assets. To disable the requirement of *ROLE_DIGITAL_TWIN_ASSETS_\\** permissions completely, the tenant option can be set to `none`.\n\nThe following elevated permissions are available for the Asset API:\n\n- *ROLE_DIGITAL_TWIN_ASSETS_CREATE*: Users can create new assets including LinkedSeries and their Source.\n- *ROLE_DIGITAL_TWIN_ASSETS_UPDATE*: Users can update existing assets including LinkedSeries and their Source.\n- *ROLE_DIGITAL_TWIN_ASSETS_ADMIN*: Users can manage all assets, including creating, updating, and deleting them.\n"
 			},
 			{
 				"name": "Linked Series",
@@ -140779,7 +141196,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"get": {
 					"tags": ["Property Definitions"],
 					"summary": "Retrieve a Property Definition by identifier",
-					"description": "Finds a `Property Definition` by its `identifier`.\n\n The `identifier` needs to point to an existing `Property Definition`. The `applicableTo` parameter is used to find the `Property Definition` that is applicable to the specified domain entity. Otherwise, this operation responds in `HTTP 404`. If no `applicableTo` is specified, the operation will return the `Property Definition` that is not applicable to any domain entity, if it exists.",
+					"description": "Finds a `Property Definition` by its `identifier`.\n\n If `applicableTo` is specified, the `identifier` needs to point to an existing `Property Definition` that is applicable to that domain entity. If `applicableTo` is not specified, the operation will return the `Property Definition` that is **not applicable to any** domain entity (i.e. where no context is applied). If no such `Property Definition` exists, it will respond with `HTTP 404`. ",
 					"operationId": "getPropertyDefinition",
 					"parameters": [{
 						"name": "identifier",
@@ -140790,7 +141207,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					}, {
 						"name": "applicableTo",
 						"in": "query",
-						"description": "Limits the response to Property Definitions applicable to the specified domain entity.",
+						"description": "Limits the response to the Property Definitions that are applicable to the specified domain entity.",
 						"schema": {
 							"type": "string",
 							"enum": [
@@ -140812,7 +141229,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"put": {
 					"tags": ["Property Definitions"],
 					"summary": "Update an existing Property Definition",
-					"description": "Updates an existing `Property Definition`.\n\n Updates the `Property Definition` that is exactly identified by the `identifier` and `contexts` in the path. The `Property Definition` must be applicable to all the specified domain entities (and no others). If no contexts is specified, the `Property Definition` that is not applicable to any domain entity will be updated. The `requestBody` is used to update the `Property Definition` with the new values. This operation is restricted to updating the existing JSON Schema (including `title` and `description`), `contexts`, `tags`, and other custom fragments. Updating the `identifier` is not permitted.",
+					"description": "Updates an existing `Property Definition`.\n\n Updates the `Property Definition` that is exactly identified by the `identifier` and `contexts` in the path. The `Property Definition` must be applicable to all the specified domain entities (and no others). If no contexts is specified, the `Property Definition` that is not applicable to any domain entity will be updated. The `requestBody` is used to update the `Property Definition` with the new values. This operation is restricted to updating the existing JSON Schema (including `title` and `description`), `contexts`, `tags`, and other custom fragments. Updating the `identifier` is not permitted. ",
 					"operationId": "updatePropertyDefinition",
 					"parameters": [{
 						"name": "identifier",
@@ -140823,7 +141240,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					}, {
 						"name": "contexts",
 						"in": "query",
-						"description": "Limits the response to Property Definitions matching exactly the specified domain entities.",
+						"description": "Indicates the resource to filter for the Property Definition that matches exactly the specified domain entities.",
 						"explode": false,
 						"schema": {
 							"type": "array",
@@ -140854,7 +141271,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"delete": {
 					"tags": ["Property Definitions"],
 					"summary": "Delete an existing Property Definition",
-					"description": "Deletes an existing `Property Definition` by its `identifier` and `contexts`.\n\n Deletes only the Property Definition that is exactly applicable to all the specified domain entities (and no others). If no contexts is specified, the operation will delete the Property Definition that is not applicable to any domain entity.",
+					"description": "Deletes an existing `Property Definition` by its `identifier` and `contexts`.\n\n Deletes only the Property Definition that is exactly applicable to all the specified domain entities (and no others). If no contexts is specified, the operation will delete the Property Definition that is not applicable to any domain entity. ",
 					"operationId": "deletePropertyDefinition",
 					"parameters": [{
 						"name": "identifier",
@@ -140865,7 +141282,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					}, {
 						"name": "contexts",
 						"in": "query",
-						"description": "Limits the response to Property Definitions matching exactly the specified domain entities.",
+						"description": "Indicates the resource to filter for the Property Definition that matches exactly the specified domain entities.",
 						"explode": false,
 						"schema": {
 							"type": "array",
@@ -140890,7 +141307,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"get": {
 					"tags": ["Measurement Definitions"],
 					"summary": "Retrieve Measurement Definitions",
-					"description": "Finds a collection of `Measurement Definition`s.\n\n This resource offers diverse filtering capabilities, yet it's essential to consider data consistency rules: \n\n * Passing only one `identifier` results in `0...1` `Measurement Definition`s.\n\n * Passing only one `title` results in `0...1` `Measurement Definition`s.\n\n\n\n\n\n The following rules will be applied when searching for the `Measurement Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.*",
+					"description": "Finds a collection of `Measurement Definition`s.\n\n This resource offers diverse filtering capabilities, yet it's essential to consider data consistency rules: \n\n * Passing only one `identifier` results in `0...1` `Measurement Definition`s.\n\n * Passing only one `title` results in `0...1` `Measurement Definition`s.\n\n  \n\n \n\n The following rules will be applied when searching for the `Measurement Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.* ",
 					"operationId": "getMeasurementDefinitions",
 					"parameters": [
 						{
@@ -140951,9 +141368,8 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							"in": "query",
 							"description": "The current page number to be retrieved.",
 							"schema": {
-								"type": "integer",
-								"format": "int32",
-								"default": 1
+								"minimum": 1,
+								"type": "integer"
 							}
 						},
 						{
@@ -140975,7 +141391,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"put": {
 					"tags": ["Measurement Definitions"],
 					"summary": "Update an existing Measurement Definition",
-					"description": "Updates an existing `Measurement Definition`.\n\n The Measurement Definition's `identifier` is taken from the `requestBody`. This operation is restricted to updating the existing JSON Schema (including `title` and `description`). No other modifications are permitted.",
+					"description": "Updates an existing `Measurement Definition`.\n\n The Measurement Definition's `identifier` is taken from the `requestBody`. This operation is restricted to updating the existing JSON Schema (including `title` and `description`). No other modifications are permitted. ",
 					"operationId": "updateMeasurementDefinition",
 					"requestBody": {
 						"description": "The data payload representing the `Measurement Definition` to be updated.",
@@ -140990,7 +141406,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"post": {
 					"tags": ["Measurement Definitions"],
 					"summary": "Create a new Measurement Definition",
-					"description": "Creates a new `Measurement Definition`.\n\n This operation ensures consistency by enforcing the following rules: \n\n * The `identifier` of the `Measurement Definition` must be unique.\n\n * If a `title` is provided, it must also be unique.\n\n\n\n\n\n The supplied JSON Schema must conform to the [JSON Schema Draft-7 specification](http://json-schema.org/draft-07/schema).",
+					"description": "Creates a new `Measurement Definition`.\n\n This operation ensures consistency by enforcing the following rules: \n\n * The `identifier` of the `Measurement Definition` must be unique.\n\n * If a `title` is provided, it must also be unique.\n\n  \n\n\n\n The supplied JSON Schema must conform to the [JSON Schema Draft-7 specification](http://json-schema.org/draft-07/schema). ",
 					"operationId": "createMeasurementDefinition",
 					"requestBody": {
 						"description": "The data payload representing the `Measurement Definition` to be created.",
@@ -141007,7 +141423,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"get": {
 					"tags": ["Event Definitions"],
 					"summary": "Retrieve Event Definitions",
-					"description": "Finds a collection of `Event Definition`s.\n\n This resource offers diverse filtering capabilities, yet it's essential to consider data consistency rules: \n\n * Passing only one `identifier` results in `0...1` `Event Definition`s.\n\n * Passing only one `title` results in `0...1` `Event Definition`s.\n\n\n\n\n\n The following rules will be applied when searching for the `Event Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.*",
+					"description": "Finds a collection of `Event Definition`s.\n\n This resource offers diverse filtering capabilities, yet it's essential to consider data consistency rules: \n\n * Passing only one `identifier` results in `0...1` `Event Definition`s.\n\n * Passing only one `title` results in `0...1` `Event Definition`s.\n\n  \n\n \n\n The following rules will be applied when searching for the `Event Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.* ",
 					"operationId": "getEventDefinitions",
 					"parameters": [
 						{
@@ -141068,9 +141484,8 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							"in": "query",
 							"description": "The current page number to be retrieved.",
 							"schema": {
-								"type": "integer",
-								"format": "int32",
-								"default": 1
+								"minimum": 1,
+								"type": "integer"
 							}
 						},
 						{
@@ -141092,7 +141507,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"put": {
 					"tags": ["Event Definitions"],
 					"summary": "Update an existing Event Definition",
-					"description": "Updates an existing `Event Definition`.\n\n The Event Definition's `identifier` is taken from the `requestBody`. This operation is restricted to updating the existing JSON Schema (including `title` and `description`). No other modifications are permitted.",
+					"description": "Updates an existing `Event Definition`.\n\n The Event Definition's `identifier` is taken from the `requestBody`. This operation is restricted to updating the existing JSON Schema (including `title` and `description`). No other modifications are permitted. ",
 					"operationId": "updateEventDefinition",
 					"requestBody": {
 						"description": "The data payload representing the `Event Definition` to be updated.",
@@ -141107,7 +141522,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"post": {
 					"tags": ["Event Definitions"],
 					"summary": "Create a new Event Definition",
-					"description": "Creates a new `Event Definition`.\n\n This operation ensures consistency by enforcing the following rules: \n\n * The `identifier` of the `Event Definition` must be unique.\n\n * If a `title` is provided, it must also be unique.\n\n\n\n\n\n The supplied JSON Schema must conform to the [JSON Schema Draft-7 specification](http://json-schema.org/draft-07/schema).",
+					"description": "Creates a new `Event Definition`.\n\n This operation ensures consistency by enforcing the following rules: \n\n * The `identifier` of the `Event Definition` must be unique.\n\n * If a `title` is provided, it must also be unique.\n\n  \n\n\n\n The supplied JSON Schema must conform to the [JSON Schema Draft-7 specification](http://json-schema.org/draft-07/schema). ",
 					"operationId": "createEventDefinition",
 					"requestBody": {
 						"description": "The data payload representing the `Event Definition` to be created.",
@@ -141124,7 +141539,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"get": {
 					"tags": ["Asset Definitions"],
 					"summary": "Retrieve Asset Definitions",
-					"description": "Finds a collection of `Asset Definition`s.\n\n This resource offers diverse filtering capabilities, yet it's essential to consider data consistency rules: \n\n * Passing only one `identifier` results in `0...1` `Asset Definition`s.\n\n * Passing only one `title` results in `0...1` `Asset Definition`s.\n\n\n\n\n\n The following rules will be applied when searching for the `Asset Definition`s: \n\n * `identifiers`, `titles`, `onlyRoots` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.*",
+					"description": "Finds a collection of `Asset Definition`s.\n\n This resource offers diverse filtering capabilities, yet it's essential to consider data consistency rules: \n\n * Passing only one `identifier` results in `0...1` `Asset Definition`s.\n\n * Passing only one `title` results in `0...1` `Asset Definition`s.\n\n  \n\n \n\n The following rules will be applied when searching for the `Asset Definition`s: \n\n * `identifiers`, `titles`, `onlyRoots` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.* ",
 					"operationId": "getAssetDefinitions",
 					"parameters": [
 						{
@@ -141194,9 +141609,8 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							"in": "query",
 							"description": "The current page number to be retrieved.",
 							"schema": {
-								"type": "integer",
-								"format": "int32",
-								"default": 1
+								"minimum": 1,
+								"type": "integer"
 							}
 						},
 						{
@@ -141218,7 +141632,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"put": {
 					"tags": ["Asset Definitions"],
 					"summary": "Update an existing Asset Definition",
-					"description": "Updates the `Asset Definition`.\n\n Throws a `ConflictException` if validation fails due to conflicts in the specified properties or sub-assets. Such conflicts occur when one or more of the provided allowed properties or sub-assets either do not exist or are not applicable within the current `asset` context.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN`*",
+					"description": "Updates the `Asset Definition`.\n\n Throws a `ConflictException` if validation fails due to conflicts in the specified properties or sub-assets. Such conflicts occur when one or more of the provided allowed properties or sub-assets either do not exist or are not applicable within the current `asset` context.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN`* ",
 					"operationId": "updateAssetDefinition",
 					"requestBody": {
 						"description": "The data payload containing only the fields that need to be updated or added to the existing `Asset Definition`. Fields\nnot included in the payload will remain unchanged.",
@@ -141250,7 +141664,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"get": {
 					"tags": ["Alarm Definitions"],
 					"summary": "Retrieve a collection of Alarm Definitions",
-					"description": "Finds a collection of `Alarm Definition`s.\n\n This resource offers diverse filtering capabilities, yet it's essential to consider data consistency rules: \n\n * Passing only one `identifier` results in `0...1` `Alarm Definition`s.\n\n * Passing only one `title` results in `0...1` `Alarm Definition`s.\n\n\n\n\n\n The following rules will be applied when searching for the `Alarm Definition`s: \n\n * `identifiers`, `titles` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.*",
+					"description": "Finds a collection of `Alarm Definition`s.\n\n This resource offers diverse filtering capabilities, yet it's essential to consider data consistency rules: \n\n * Passing only one `identifier` results in `0...1` `Alarm Definition`s.\n\n * Passing only one `title` results in `0...1` `Alarm Definition`s.\n\n  \n\n \n\n The following rules will be applied when searching for the `Alarm Definition`s: \n\n * `identifiers`, `titles` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.* ",
 					"operationId": "getAlarmDefinitions",
 					"parameters": [
 						{
@@ -141311,9 +141725,8 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							"in": "query",
 							"description": "The current page number to be retrieved.",
 							"schema": {
-								"type": "integer",
-								"format": "int32",
-								"default": 1
+								"minimum": 1,
+								"type": "integer"
 							}
 						},
 						{
@@ -141335,7 +141748,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"put": {
 					"tags": ["Alarm Definitions"],
 					"summary": "Update an existing Alarm Definition",
-					"description": "Updates an existing `Alarm Definition`.\n\n The Alarm Definition's `identifier` is taken from the `requestBody`. This operation is restricted to updating the existing JSON Schema (including `title` and `description`). No other modifications are permitted.",
+					"description": "Updates an existing `Alarm Definition`.\n\n The Alarm Definition's `identifier` is taken from the `requestBody`. This operation is restricted to updating the existing JSON Schema (including `title` and `description`). No other modifications are permitted. ",
 					"operationId": "updateAlarmDefinition",
 					"requestBody": {
 						"description": "The data payload representing the `Alarm Definition` to be updated.",
@@ -141350,7 +141763,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"post": {
 					"tags": ["Alarm Definitions"],
 					"summary": "Create a new Alarm Definition",
-					"description": "Creates a new `Alarm Definition`.\n\n This operation ensures consistency by enforcing the following rules: \n\n * The `identifier` of the `Alarm Definition` must be unique.\n\n * If a `title` is provided, it must also be unique.\n\n\n\n\n\n The supplied JSON Schema must conform to the [JSON Schema Draft-7 specification](http://json-schema.org/draft-07/schema).",
+					"description": "Creates a new `Alarm Definition`.\n\n This operation ensures consistency by enforcing the following rules: \n\n * The `identifier` of the `Alarm Definition` must be unique.\n\n * If a `title` is provided, it must also be unique.\n\n  \n\n\n\n The supplied JSON Schema must conform to the [JSON Schema Draft-7 specification](http://json-schema.org/draft-07/schema). ",
 					"operationId": "createAlarmDefinition",
 					"requestBody": {
 						"description": "The data payload representing the `Alarm Definition` to be created.",
@@ -141388,7 +141801,8 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 						{
 							"name": "withSubAssets",
 							"in": "query",
-							"description": "Indicates the resource to add the sub-assets in the response.",
+							"description": "**Deprecated** – use the dedicated `/assets/{assetId}/subAssets`, `/assets/externalIds/{externalId}/subAssets` or `/assets/subAssets` endpoint instead!<br>Indicates the resource to add the sub-assets in the response.",
+							"deprecated": true,
 							"schema": {
 								"type": "boolean",
 								"default": false
@@ -141402,6 +141816,24 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 								"type": "boolean",
 								"default": false
 							}
+						},
+						{
+							"name": "withParents",
+							"in": "query",
+							"description": "Indicates the resource to add the parent assets in the response.",
+							"schema": {
+								"type": "boolean",
+								"default": false
+							}
+						},
+						{
+							"name": "withChildrenCount",
+							"in": "query",
+							"description": "Indicates the resource to include the total number of child entities (sub-assets and devices) in the response.",
+							"schema": {
+								"type": "boolean",
+								"default": false
+							}
 						}
 					],
 					"responses": { "200": {
@@ -141412,7 +141844,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"put": {
 					"tags": ["Assets"],
 					"summary": "Update an existing asset",
-					"description": "Updates an existing asset. All properties of the asset can be updated, including `name`, `type`,\n`c8y_ExternalId`, and fragments - except the `id`. Missing properties in the request body will not be removed but stay\nunchanged. Fragments, however, will be replaced completely, so missing properties in a fragment will be removed. If you want to remove a\nfragment, you have to explicitly set it to `null`. If the `c8y_ExternalId` is different to the existing Asset, it will be\nupdated accordingly. If the new `c8y_ExternalId` already exists, a conflict error will be returned.\n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_UPDATE` **AND** `ROLE_INVENTORY_ADMIN`*",
+					"description": "Updates an existing asset. All properties of the asset can be updated, including `name`, `type`,\n`c8y_ExternalId`, and fragments - except the `id`. Missing properties in the request body will not be removed but stay\nunchanged. Fragments, however, will be replaced completely, so missing properties in a fragment will be removed. If you want to remove a\nfragment, you have to explicitly set it to `null`. If the `c8y_ExternalId` is different to the existing Asset, it will be\nupdated accordingly. If the new `c8y_ExternalId` already exists, a conflict error will be returned.\n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_UPDATE` **AND** `ROLE_INVENTORY_ADMIN`* (depending on the setting of `assets.permission.mode` as described in the Permissions section) ",
 					"operationId": "updateAsset",
 					"parameters": [{
 						"name": "assetId",
@@ -141440,14 +141872,34 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"delete": {
 					"tags": ["Assets"],
 					"summary": "Delete an existing asset",
-					"description": "Deletes an existing asset.\n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN`*",
+					"description": "Deletes an existing asset and optionally its hierarchy consisting of all assigned sub-assets and/or all assigned devices. Sub-assets and\ndevices which are also assigned to other parent assets outside the hierarchy, will not be deleted but only unassigned from the deleted asset.\n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN`* (depending on the setting of `assets.permission.mode` as described in the Permissions section) ",
 					"operationId": "deleteAsset",
-					"parameters": [{
-						"name": "assetId",
-						"in": "path",
-						"required": true,
-						"schema": { "type": "string" }
-					}],
+					"parameters": [
+						{
+							"name": "assetId",
+							"in": "path",
+							"required": true,
+							"schema": { "type": "string" }
+						},
+						{
+							"name": "deleteSubAssets",
+							"in": "query",
+							"description": "Indicates whether the resource also deletes sub-assets. If `false`, sub-assets are only unassigned from the deleted asset but not deleted themselves.",
+							"schema": {
+								"type": "boolean",
+								"default": true
+							}
+						},
+						{
+							"name": "deleteDevices",
+							"in": "query",
+							"description": "Indicates whether the resource also deletes devices (managed objects with the `c8y_IsDevice` fragment) whose all parent assets are being deleted.",
+							"schema": {
+								"type": "boolean",
+								"default": false
+							}
+						}
+					],
 					"responses": { "204": { "description": "No Content" } }
 				}
 			},
@@ -141455,7 +141907,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"get": {
 					"tags": ["Linked Series"],
 					"summary": "Retrieve the source for a given linked series",
-					"description": "Retrieves the source for a given linked series of an asset.\n\n Linked series are identified by their `fragment` **and** `series`.",
+					"description": "Retrieves the source for a given linked series of an asset.\n\n Linked series are identified by their `fragment` **and** `series`. ",
 					"operationId": "getLinkedSeriesSource",
 					"parameters": [
 						{
@@ -141485,7 +141937,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"put": {
 					"tags": ["Linked Series"],
 					"summary": "Update the source for a given linked series",
-					"description": "Updates an existing source for a given linked series of an asset.\n\n Linked series are identified by their `fragment` **and** `series`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_UPDATE` or `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` or `ROLE_DIGITAL_TWIN_LINKING_UPDATE` or `ROLE_DIGITAL_TWIN_LINKING_ADMIN`*.",
+					"description": "Updates an existing source for a given linked series of an asset.\n\n Linked series are identified by their `fragment` **and** `series`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_UPDATE` or `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` or `ROLE_DIGITAL_TWIN_LINKING_UPDATE` or `ROLE_DIGITAL_TWIN_LINKING_ADMIN`*. ",
 					"operationId": "updateLinkedSeriesSource",
 					"parameters": [
 						{
@@ -141528,7 +141980,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"post": {
 					"tags": ["Linked Series"],
 					"summary": "Set the source for a given linked series",
-					"description": "Adds a new source for a given linked series of an asset.\n\n Linked series are identified by their `fragment` **and** `series`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_CREATE` or `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` or `ROLE_DIGITAL_TWIN_LINKING_CREATE` or `ROLE_DIGITAL_TWIN_LINKING_ADMIN`*.",
+					"description": "Adds a new source for a given linked series of an asset.\n\n Linked series are identified by their `fragment` **and** `series`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_CREATE` or `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` or `ROLE_DIGITAL_TWIN_LINKING_CREATE` or `ROLE_DIGITAL_TWIN_LINKING_ADMIN`*. ",
 					"operationId": "createLinkedSeriesSource",
 					"parameters": [
 						{
@@ -141571,7 +142023,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"delete": {
 					"tags": ["Linked Series"],
 					"summary": "Delete the source for a given linked series",
-					"description": "Deletes an existing source for a given linked series of an asset.\n\n Linked series are identified by their `fragment` **and** `series`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` or `ROLE_DIGITAL_TWIN_LINKING_ADMIN`*.",
+					"description": "Deletes an existing source for a given linked series of an asset.\n\n Linked series are identified by their `fragment` **and** `series`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` or `ROLE_DIGITAL_TWIN_LINKING_ADMIN`*. ",
 					"operationId": "deleteLinkedSeriesSource",
 					"parameters": [
 						{
@@ -141599,7 +142051,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 			"/service/dtm/assets/{assetId}/linkedSeries/{fragment}/{series}/source/type": { "put": {
 				"tags": ["Linked Series"],
 				"summary": "Update the measurement type of a linked series source",
-				"description": "Modifies the `type` of a source of a linked series for a given asset. If the `fetchTypeFromSource` is set to\n`true`, the type specified in the body of the request will be ignored. Instead, the value is fetched from the last measurement of\nthe device defined by the which `source.id`.",
+				"description": "Modifies the `type` of a source of a linked series for a given asset. If the `fetchTypeFromSource` is set to\n`true`, the type specified in the body of the request will be ignored. Instead, the value is fetched from the last measurement of\nthe device defined by the which `source.id`.\n\n Using `content-type=application/json` is deprecated, use `content-type=text/plain` instead. ",
 				"operationId": "updateMeasurementType",
 				"parameters": [
 					{
@@ -141630,16 +142082,61 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 						}
 					}
 				],
-				"requestBody": { "content": { "application/json": { "schema": { "type": "string" } } } },
+				"requestBody": { "content": {
+					"text/plain": { "schema": { "type": "string" } },
+					"application/json": { "schema": { "type": "string" } }
+				} },
 				"responses": { "200": {
 					"description": "OK",
 					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Source" } } }
 				} }
 			} },
+			"/service/dtm/assets/{assetId}/linkedSeries/{fragment}/{series}/reconcileOpposite": { "put": {
+				"tags": ["Linked Series"],
+				"summary": "Reconcile the opposite link for a linked series",
+				"description": "Reconciles the opposite link (MeasurementSourceLink) for a given linked series.\n\n Recreates or updates the LinkedAsset representation in the device's MeasurementSourceLink (c8y_LinkedSeriesReverseIndex) referenced by the LinkedSeries' `source.id`, ensuring bidirectional link consistency.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_UPDATE` or `ROLE_DIGITAL_TWIN_ASSETS_ADMIN`*. ",
+				"operationId": "reconcileOppositeLink",
+				"parameters": [
+					{
+						"name": "assetId",
+						"in": "path",
+						"required": true,
+						"schema": { "type": "string" }
+					},
+					{
+						"name": "fragment",
+						"in": "path",
+						"required": true,
+						"schema": { "type": "string" }
+					},
+					{
+						"name": "series",
+						"in": "path",
+						"required": true,
+						"schema": { "type": "string" }
+					},
+					{
+						"name": "removeMissingSourceId",
+						"in": "query",
+						"description": "Indicates the resource to remove the `id` of the source of the Linked Series if the device with the given id does not exist. This can be used to automatically clean up Linked Series with non-existing sources.",
+						"schema": {
+							"type": "boolean",
+							"default": false
+						}
+					}
+				],
+				"responses": {
+					"200": {
+						"description": "OK",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedAsset" } } }
+					},
+					"204": { "description": "No Content" }
+				}
+			} },
 			"/service/dtm/assets/{assetId}/linkedSeries/{fragment}/{series}/label": { "put": {
 				"tags": ["Linked Series"],
 				"summary": "Update the label of a linked series",
-				"description": "Modifies the `label` of a linked series for a given asset.",
+				"description": "Modifies the `label` of a linked series for a given asset.\n\n Using `content-type=application/json` is deprecated, use `content-type=text/plain` instead. ",
 				"operationId": "updateLabel",
 				"parameters": [
 					{
@@ -141662,7 +142159,10 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					}
 				],
 				"requestBody": {
-					"content": { "application/json": { "schema": { "type": "string" } } },
+					"content": {
+						"text/plain": { "schema": { "type": "string" } },
+						"application/json": { "schema": { "type": "string" } }
+					},
 					"required": true
 				},
 				"responses": { "200": {
@@ -141670,11 +142170,41 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedSeries" } } }
 				} }
 			} },
+			"/service/dtm/assets/{assetId}/linkedSeries/reconcileOpposite": { "put": {
+				"tags": ["Linked Series"],
+				"summary": "Reconcile the opposite links for all linked series of an asset",
+				"description": "Reconciles the opposite links (MeasurementSourceLink) for all LinkedSeries with a `source.id` in the given asset.\n\n For each LinkedSeries with a `source.id`, recreates or updates the LinkedAsset representation in the device's MeasurementSourceLink (c8y_LinkedSeriesReverseIndex), ensuring bidirectional link consistency across the whole asset.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_UPDATE` or `ROLE_DIGITAL_TWIN_ASSETS_ADMIN`*. ",
+				"operationId": "reconcileOppositeLinks",
+				"parameters": [{
+					"name": "assetId",
+					"in": "path",
+					"required": true,
+					"schema": { "type": "string" }
+				}, {
+					"name": "removeMissingSourceId",
+					"in": "query",
+					"description": "Indicates the resource to remove the `id` of the source of the Linked Series if the device with the given id does not exist. This can be used to automatically clean up Linked Series with non-existing sources.",
+					"schema": {
+						"type": "boolean",
+						"default": false
+					}
+				}],
+				"responses": {
+					"200": {
+						"description": "OK",
+						"content": { "application/json": { "schema": {
+							"type": "array",
+							"items": { "$ref": "#/components/schemas/LinkedAsset" }
+						} } }
+					},
+					"204": { "description": "No Content" }
+				}
+			} },
 			"/service/dtm/definitions/properties": {
 				"get": {
 					"tags": ["Property Definitions"],
 					"summary": "Retrieve all Property Definitions",
-					"description": "Finds a collection of `Property Definition`s.\n\n This resource offers diverse filtering capabilities, yet it's essential to consider data consistency rules: \n\n * Passing only one `identifier` results in `0...1` `Property Definition`s.\n\n * Passing only one `title` results in `0...1` `Property Definition`s.\n\n\n\n\n\n The following rules will be applied when searching for the `Property Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `<i>Will be executed in context of an `Storage` tenant.</i>",
+					"description": "Finds a collection of `Property Definition`s.\n\n This resource offers diverse filtering capabilities, yet it's essential to consider data consistency rules: \n\n * Passing only one `identifier` results in `0...1` `Property Definition`s.\n\n * Passing only one `title` results in `0...1` `Property Definition`s.\n\n  \n\n \n\n The following rules will be applied when searching for the `Property Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `<i>Will be executed in context of an `Storage` tenant.</i>",
 					"operationId": "getPropertyDefinitions",
 					"parameters": [
 						{
@@ -141739,7 +142269,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 						{
 							"name": "applicableTo",
 							"in": "query",
-							"description": "Limits the response to Property Definitions applicable to the specified domain entity.",
+							"description": "Limits the response to the Property Definitions that are applicable to the specified domain entity.",
 							"schema": {
 								"type": "string",
 								"enum": [
@@ -141758,9 +142288,8 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							"in": "query",
 							"description": "The current page number to be retrieved.",
 							"schema": {
-								"type": "integer",
-								"format": "int32",
-								"default": 1
+								"minimum": 1,
+								"type": "integer"
 							}
 						},
 						{
@@ -141782,7 +142311,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"post": {
 					"tags": ["Property Definitions"],
 					"summary": "Create a new Property Definition",
-					"description": "Creates a new `Property Definition`.\n\n This operation ensures consistency by enforcing the following rules: \n\n * The `identifier` of the `Property Definition` must be unique for the given `context`s.\n\n * If a `title` is provided, it must also be unique.\n\n * None of the `context`s must not be used by another `Property Definition` with the same `identifier`.\n\n\n\n\n\n The supplied JSON Schema must conform to the [JSON Schema Draft-7 specification](http://json-schema.org/draft-07/schema).",
+					"description": "Creates a new `Property Definition`.\n\n This operation ensures consistency by enforcing the following rules: \n\n * The `identifier` of the `Property Definition` must be unique for the given `context`s.\n\n * If a `title` is provided, it must also be unique.\n\n * None of the `context`s must not be used by another `Property Definition` with the same `identifier`.\n\n  \n\n\n\n The supplied JSON Schema must conform to the [JSON Schema Draft-7 specification](http://json-schema.org/draft-07/schema). ",
 					"operationId": "createPropertyDefinition",
 					"requestBody": {
 						"description": "The data payload representing the `Property Definition` to be created.",
@@ -141798,7 +142327,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 			"/service/dtm/definitions/properties/compose": { "post": {
 				"tags": ["Property Definitions"],
 				"summary": "Create JSON schema from Property Definitions",
-				"description": "Creates a JSON schema object type.\n\n This operation constructs a JSON Schema object type that encapsulates one or more `Property Definition`s as its properties. The resulting schema will include all provided `Property Definition`s. \n\n The `Property Definition`s to be included are supplied in the request body. At least one `Property Definition` must be provided and identified by its `identifier`. If a `Property Definition` applies to a specific domain entity, a corresponding `context` must also be supplied.",
+				"description": "Creates a JSON schema object type.\n\n This operation constructs a JSON Schema object type that encapsulates one or more `Property Definition`s as its properties. The resulting schema will include all provided `Property Definition`s. \n\n The `Property Definition`s to be included are supplied in the request body. At least one `Property Definition` must be provided and identified by its `identifier`. If a `Property Definition` applies to a specific domain entity, a corresponding `context` must also be supplied. ",
 				"operationId": "composePropertyDefinitions",
 				"requestBody": {
 					"content": { "application/json": { "schema": {
@@ -141816,7 +142345,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"get": {
 					"tags": ["Assets"],
 					"summary": "Retrieve assets",
-					"description": "Retrieves all assets registered in your tenant.\n\n The `query` parameter supports a flexible syntax for filtering and ordering results.",
+					"description": "Retrieves all assets registered in your tenant.\n\n The `query` parameter supports a flexible syntax for filtering and ordering results. ",
 					"operationId": "getAssets",
 					"parameters": [
 						{
@@ -141854,7 +142383,17 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 						{
 							"name": "withSubAssets",
 							"in": "query",
-							"description": "Indicates the resource to add the sub-assets in the response.",
+							"description": "**Deprecated** – use the dedicated `/assets/{assetId}/subAssets`, `/assets/externalIds/{externalId}/subAssets` or `/assets/subAssets` endpoint instead!<br>Indicates the resource to add the sub-assets in the response.",
+							"deprecated": true,
+							"schema": {
+								"type": "boolean",
+								"default": false
+							}
+						},
+						{
+							"name": "withParents",
+							"in": "query",
+							"description": "Indicates the resource to add the parent assets in the response.",
 							"schema": {
 								"type": "boolean",
 								"default": false
@@ -141868,13 +142407,30 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 								"default": false
 							}
 						},
+						{
+							"name": "includeGroups",
+							"in": "query",
+							"description": "Indicates the resource to include assets and device groups in the response. If `false`, only assets are included.",
+							"schema": {
+								"type": "boolean",
+								"default": false
+							}
+						},
+						{
+							"name": "withChildrenCount",
+							"in": "query",
+							"description": "Indicates the resource to include the total number of child entities (sub-assets and devices) in the response.",
+							"schema": {
+								"type": "boolean",
+								"default": false
+							}
+						},
 						{
 							"name": "currentPage",
 							"in": "query",
 							"schema": {
-								"type": "integer",
-								"format": "int32",
-								"default": 1
+								"minimum": 1,
+								"type": "integer"
 							}
 						},
 						{
@@ -141895,7 +142451,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"post": {
 					"tags": ["Assets"],
 					"summary": "Create or update an asset",
-					"description": "Creates or updates an Asset, for example, a room within a building.\n\n In general, each asset may consist of: \n\n * The name of the asset.\n\n * The most specific type of the asset.\n\n * Fragments with specific meanings, for example, c8y_Position, c8y_SupportedOperations.\n\n * Fragment `c8y_ExternalId` which uniquely identifies the asset in an external system.\n\n * If a value for the property `id` is provided, it will be ignored.\n\n\n\n If an asset with the given external ID exists and `X-Upsert-Mode` is true, the asset will be updated and the response code will be 200. If an asset with the given external ID exists and `X-Upsert-Mode` is false, a conflict error will be returned. If no asset with the given external ID exists, a new asset will be created (independent of the `X-Upsert-Mode`) and the response code will be 201.",
+					"description": "Creates or updates an Asset, for example, a room within a building.\n\n In general, each asset may consist of: \n\n * The name of the asset.\n\n * The most specific type of the asset.\n\n * Fragments with specific meanings, for example, c8y_Position, c8y_SupportedOperations.\n\n * Fragment `c8y_ExternalId` which uniquely identifies the asset in an external system.\n\n * If a value for the property `id` is provided, it will be ignored.\n\n  \n\n If an asset with the given external ID exists and `X-Upsert-Mode` is true, the asset will be updated and the response code will be 200. If an asset with the given external ID exists and `X-Upsert-Mode` is false, a conflict error will be returned. If no asset with the given external ID exists, a new asset will be created (independent of the `X-Upsert-Mode`) and the response code will be 201.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_CREATE` **AND** `ROLE_INVENTORY_ADMIN`* (depending on the setting of `assets.permission.mode` as described in the Permissions section) ",
 					"operationId": "createAsset",
 					"parameters": [{
 						"name": "fetchTypeFromSource",
@@ -141927,11 +142483,127 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					}
 				}
 			},
+			"/service/dtm/assets/{assetId}/subAssets": {
+				"get": {
+					"tags": ["Assets"],
+					"summary": "Retrieve sub-assets of an asset",
+					"description": "Retrieves sub-assets of an asset.\n\n Fetches all sub-assets of the parent asset specified by `assetId`. ",
+					"operationId": "getSubAssets",
+					"parameters": [
+						{
+							"name": "assetId",
+							"in": "path",
+							"required": true,
+							"schema": { "type": "string" }
+						},
+						{
+							"name": "query",
+							"in": "query",
+							"description": "Use the `$filter` keyword to specify filtering criteria. Filtering can be applied to properties of the asset. Detailed information can be found within the Cumulocity core OpenAPI [here](https://cumulocity.com/api/core/#tag/Query-language).",
+							"schema": {
+								"type": "string",
+								"format": "c8y:query"
+							},
+							"examples": {
+								"Filter by name": {
+									"description": "Filter by name",
+									"value": "$filter=name eq 'Windfarm'"
+								},
+								"Filter by type": {
+									"description": "Filter by type",
+									"value": "$filter=type eq 'c8y_*'"
+								},
+								"Using orderby": {
+									"description": "Using orderby",
+									"value": "$orderby=id asc"
+								}
+							}
+						},
+						{
+							"name": "withLinkedSeries",
+							"in": "query",
+							"description": "Indicates the resource to add the `c8y_LinkedSeries` fragment in the response.",
+							"schema": {
+								"type": "boolean",
+								"default": false
+							}
+						},
+						{
+							"name": "withParents",
+							"in": "query",
+							"description": "Indicates the resource to add the parent assets in the response.",
+							"schema": {
+								"type": "boolean",
+								"default": false
+							}
+						},
+						{
+							"name": "includeGroups",
+							"in": "query",
+							"description": "Indicates the resource to include assets and device groups in the response. If `false`, only assets are included.",
+							"schema": {
+								"type": "boolean",
+								"default": false
+							}
+						},
+						{
+							"name": "withChildrenCount",
+							"in": "query",
+							"description": "Indicates the resource to include the total number of child entities (sub-assets and devices) in the response.",
+							"schema": {
+								"type": "boolean",
+								"default": false
+							}
+						},
+						{
+							"name": "currentPage",
+							"in": "query",
+							"schema": {
+								"minimum": 1,
+								"type": "integer"
+							}
+						},
+						{
+							"name": "pageSize",
+							"in": "query",
+							"schema": {
+								"maximum": 2e3,
+								"minimum": 1,
+								"type": "integer"
+							}
+						}
+					],
+					"responses": { "200": {
+						"description": "OK",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetList" } } }
+					} }
+				},
+				"post": {
+					"tags": ["Assets"],
+					"summary": "Create and assign a sub-asset in one operation",
+					"description": "Creates a new sub-asset and assigns it to the parent asset in one operation.\n\n Creates a new asset from the provided payload and immediately assigns it as a sub-asset to the specified parent asset. If the parent asset does not exist, the operation responds with `HTTP 404`. If the parent asset or the payload is not of type Asset, the operation responds with `HTTP 422`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN`* (depending on the setting of `assets.permission.mode` as described in the Permissions section) ",
+					"operationId": "createAndAssignSubAsset",
+					"parameters": [{
+						"name": "assetId",
+						"in": "path",
+						"required": true,
+						"schema": { "type": "string" }
+					}],
+					"requestBody": {
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } },
+						"required": true
+					},
+					"responses": { "201": {
+						"description": "Created",
+						"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } }
+					} }
+				}
+			},
 			"/service/dtm/assets/{assetId}/subAssets/{subAssetId}": {
 				"post": {
 					"tags": ["Assets"],
 					"summary": "Assign an asset as a sub-asset",
-					"description": "Assigns an asset as a sub-asset.\n\n Associates the specified asset, identified by its ID, with a parent asset. The sub-asset must already exist. If one of the IDs does not exist, the operation responds with `HTTP 404`. If one of the IDs is not an Asset, the operation responds with `HTTP 422`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN`*",
+					"description": "Assigns an asset as a sub-asset.\n\n Associates the specified asset, identified by its ID, with a parent asset. The sub-asset must already exist. If one of the IDs does not exist, the operation responds with `HTTP 404`. If one of the IDs is not an Asset, the operation responds with `HTTP 422`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN`* (depending on the setting of `assets.permission.mode` as described in the Permissions section) ",
 					"operationId": "assignSubAsset",
 					"parameters": [{
 						"name": "assetId",
@@ -141952,7 +142624,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"delete": {
 					"tags": ["Assets"],
 					"summary": "Remove a sub-asset from its parent asset",
-					"description": "Removes a sub-asset from its parent asset.\n\n Removes the association of the specified asset, identified by its ID, with a parent asset. If one of the IDs does not exist, the operation responds with `HTTP 404`. If one of the IDs is not an Asset, the operation responds with `HTTP 422`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN`*",
+					"description": "Removes a sub-asset from its parent asset.\n\n Removes the association of the specified asset, identified by its ID, with a parent asset. If one of the IDs does not exist, the operation responds with `HTTP 404`. If one of the IDs is not an Asset, the operation responds with `HTTP 422`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN`* (depending on the setting of `assets.permission.mode` as described in the Permissions section) ",
 					"operationId": "unassignSubAsset",
 					"parameters": [{
 						"name": "assetId",
@@ -141972,7 +142644,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"get": {
 					"tags": ["Linked Series"],
 					"summary": "Retrieve linked series for an asset",
-					"description": "Retrieves linked series for a given asset.\n\n Supports optionally searching for a specific `fragment` and/or `series`.  \n\n The `withMeasurementType` query parameter is used to explicitly query the `type` of the measurements which are linked via the `source.id`. This parameter is only relevant if only one `LinkedSeries` is to be returned.",
+					"description": "Retrieves linked series for a given asset.\n\n Supports optionally searching for a specific `fragment` and/or `series`.  \n\n The `withMeasurementType` query parameter is used to explicitly query the `type` of the measurements which are linked via the `source.id`. This parameter is only relevant if only one `LinkedSeries` is to be returned. ",
 					"operationId": "getLinkedSeries",
 					"parameters": [
 						{
@@ -142005,7 +142677,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 						{
 							"name": "withJsonSchema",
 							"in": "query",
-							"description": "If true, the response includes the inferred JSON schema describing all linked series of this Asset.",
+							"description": "If `true`, the response includes the inferred JSON schema describing all linked series of this Asset.",
 							"schema": {
 								"type": "boolean",
 								"default": false
@@ -142015,9 +142687,8 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							"name": "currentPage",
 							"in": "query",
 							"schema": {
-								"type": "integer",
-								"format": "int32",
-								"default": 1
+								"minimum": 1,
+								"type": "integer"
 							}
 						},
 						{
@@ -142044,7 +142715,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"post": {
 					"tags": ["Linked Series"],
 					"summary": "Add new and update existing linked series",
-					"description": "Adds new and updates existing linked series for a given asset.\n\n Linked series are identified by their `fragment` **and** `series`.  \n\n For each LinkedSeries provided in the body: \n\n * Adds the new linked series when it does not exist.\n\n * Updates the linked series when it already exists.\n\n\n\n\n\n *Required user role for adding a linked series: `ROLE_DIGITAL_TWIN_ASSETS_CREATE` or `ROLE_DIGITAL_TWIN_ASSETS_ADMIN`*.\n\n *Required user role for updating a linked series: `ROLE_DIGITAL_TWIN_ASSETS_UPDATE` or `ROLE_DIGITAL_TWIN_ASSETS_ADMIN`*.",
+					"description": "Adds new and updates existing linked series for a given asset.\n\n Linked series are identified by their `fragment` **and** `series`.  \n\n For each LinkedSeries provided in the body: \n\n * Adds the new linked series when it does not exist.\n\n * Updates the linked series when it already exists.\n\n  \n\n \n\n The update behavior preserves the existing `source.id` when the Linked Series to be updated does not explicitly provide a non-blank `source.id` in the request body. If the `source.id` is provided, it will be updated accordingly.  \n\n *Required user role for adding a linked series: `ROLE_DIGITAL_TWIN_ASSETS_CREATE` or `ROLE_DIGITAL_TWIN_ASSETS_ADMIN`*.\n\n *Required user role for updating a linked series: `ROLE_DIGITAL_TWIN_ASSETS_UPDATE` or `ROLE_DIGITAL_TWIN_ASSETS_ADMIN`*. ",
 					"operationId": "addAndUpdateLinkedSeries",
 					"parameters": [{
 						"name": "assetId",
@@ -142075,7 +142746,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"delete": {
 					"tags": ["Linked Series"],
 					"summary": "Delete a specific linked series",
-					"description": "Deletes a linked series for a given asset.\n\n Deletes all linked series. Specify `fragment` and/or `series` as query parameters to be more specific about the linked series to be deleted.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN`*.",
+					"description": "Deletes a linked series for a given asset.\n\n Deletes all linked series. Specify `fragment` and/or `series` as query parameters to be more specific about the linked series to be deleted.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN`*. ",
 					"operationId": "deleteLinkedSeries",
 					"parameters": [
 						{
@@ -142104,7 +142775,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"post": {
 					"tags": ["Assets"],
 					"summary": "Assign a device to an asset",
-					"description": "Assigns a device to an asset.\n\n Associates the specified device, identified by its ID, with an asset. The device must already exist. If one of the IDs does not exist, the operation responds with `HTTP 404`. If the managed object for the assetId is not an asset or of the managed object for the deviceId is not a Device, the operation responds with `HTTP 422`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN`*",
+					"description": "Assigns a device to an asset.\n\n Associates the specified device, identified by its ID, with an asset. The device must already exist. If one of the IDs does not exist, the operation responds with `HTTP 404`. If the managed object for the assetId is not an asset or if the managed object for the deviceId is not a Device, the operation responds with `HTTP 422`.  \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN` or `ROLE_DIGITAL_TWIN_LINKING_UPDATE`* (depending on the setting of `assets.permission.mode` as described in the Permissions section) ",
 					"operationId": "assignDevice",
 					"parameters": [{
 						"name": "assetId",
@@ -142125,7 +142796,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"delete": {
 					"tags": ["Assets"],
 					"summary": "Remove a device from an asset",
-					"description": "Removes a device from an asset.\n\n Removes the association of the specified device, identified by its ID, with an asset. If one of the IDs does not exist, the operation responds with `HTTP 404`. If the managed object for the assetId is not an asset or of the managed object for the deviceId is not a Device, the operation responds with `HTTP 422`. \n\n\n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN`*",
+					"description": "Removes a device from an asset.\n\n Removes the association of the specified device, identified by its ID, with an asset. If one of the IDs does not exist, the operation responds with `HTTP 404`. If the managed object for the assetId is not an asset or if the managed object for the deviceId is not a Device, the operation responds with `HTTP 422`. \n\n \n\n *Required user role: `ROLE_DIGITAL_TWIN_ASSETS_ADMIN` **AND** `ROLE_INVENTORY_ADMIN` or `ROLE_DIGITAL_TWIN_LINKING_UPDATE`* (depending on the setting of `assets.permission.mode` as described in the Permissions section) ",
 					"operationId": "unassignDevice",
 					"parameters": [{
 						"name": "assetId",
@@ -142176,7 +142847,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 			"/service/dtm/definitions/properties/count": { "get": {
 				"tags": ["Property Definitions"],
 				"summary": "Get the count of all Property Definitions",
-				"description": "Counts the collection of `Property Definition`s.\n\n The following rules will be applied when searching for the `Property Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.*",
+				"description": "Counts the collection of `Property Definition`s.\n\n The following rules will be applied when searching for the `Property Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.* ",
 				"operationId": "countPropertyDefinitions",
 				"parameters": [
 					{
@@ -142212,7 +142883,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					{
 						"name": "applicableTo",
 						"in": "query",
-						"description": "Limits the response to Property Definitions applicable to the specified domain entity.",
+						"description": "Limits the response to the Property Definitions that are applicable to the specified domain entity.",
 						"schema": {
 							"type": "string",
 							"enum": [
@@ -142236,7 +142907,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"get": {
 					"tags": ["Measurement Definitions"],
 					"summary": "Retrieve a Measurement Definition by identifier",
-					"description": "Finds a `Measurement Definition` by its `identifier`.\n\n The `identifier` needs to point to an existing `Measurement Definition`, otherwise this operation responds in `HTTP 404`.",
+					"description": "Finds a `Measurement Definition` by its `identifier`.\n\n The `identifier` needs to point to an existing `Measurement Definition`, otherwise this operation responds in `HTTP 404`. ",
 					"operationId": "getMeasurementDefinition",
 					"parameters": [{
 						"name": "identifier",
@@ -142300,7 +142971,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 			"/service/dtm/definitions/measurements/count": { "get": {
 				"tags": ["Measurement Definitions"],
 				"summary": "Get the count of all Measurement Definitions",
-				"description": "Counts the collection of `Measurement Definition`s.\n\n The following rules will be applied when searching for the `Measurement Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.*",
+				"description": "Counts the collection of `Measurement Definition`s.\n\n The following rules will be applied when searching for the `Measurement Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.* ",
 				"operationId": "countMeasurementDefinitions",
 				"parameters": [
 					{
@@ -142343,7 +143014,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"get": {
 					"tags": ["Event Definitions"],
 					"summary": "Retrieve an Event Definition by identifier",
-					"description": "Finds a `Event Definition` by its `identifier`.\n\n The `identifier` needs to point to an existing `Event Definition`, otherwise this operation responds in `HTTP 404`.",
+					"description": "Finds a `Event Definition` by its `identifier`.\n\n The `identifier` needs to point to an existing `Event Definition`, otherwise this operation responds in `HTTP 404`. ",
 					"operationId": "getEventDefinition",
 					"parameters": [{
 						"name": "identifier",
@@ -142407,7 +143078,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 			"/service/dtm/definitions/events/count": { "get": {
 				"tags": ["Event Definitions"],
 				"summary": "Get the count of all Event Definitions",
-				"description": "Counts the collection of `Event Definition`s.\n\n The following rules will be applied when searching for the `Event Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.*",
+				"description": "Counts the collection of `Event Definition`s.\n\n The following rules will be applied when searching for the `Event Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.* ",
 				"operationId": "countEventDefinitions",
 				"parameters": [
 					{
@@ -142450,7 +143121,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"get": {
 					"tags": ["Asset Definitions"],
 					"summary": "Retrieve an Asset Definition by identifier",
-					"description": "Finds a `Asset Definition` by its `identifier`.\n\n The `identifier` needs to point to an existing `Asset Definition`, otherwise this operation responds in `HTTP 404`.",
+					"description": "Finds a `Asset Definition` by its `identifier`.\n\n The `identifier` needs to point to an existing `Asset Definition`, otherwise this operation responds in `HTTP 404`. ",
 					"operationId": "getAssetDefinition",
 					"parameters": [{
 						"name": "identifier",
@@ -142482,7 +143153,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 			"/service/dtm/definitions/assets/count": { "get": {
 				"tags": ["Asset Definitions"],
 				"summary": "Get count of Asset Definitions",
-				"description": "Counts the collection of `Asset Definition`s.\n\n The following rules will be applied when searching for the `Asset Definition`s: \n\n * `identifiers`, `titles`, `onlyRoots` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.*",
+				"description": "Counts the collection of `Asset Definition`s.\n\n The following rules will be applied when searching for the `Asset Definition`s: \n\n * `identifiers`, `titles`, `onlyRoots` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.* ",
 				"operationId": "countAssetDefinitions",
 				"parameters": [
 					{
@@ -142534,7 +143205,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				"get": {
 					"tags": ["Alarm Definitions"],
 					"summary": "Retrieve an Alarm Definition by identifier",
-					"description": "Retrieves an `Alarm Definition` by its `identifier`.\n\n The `identifier` needs to point to an existing `Alarm Definition`, otherwise this operation respond in `HTTP 404`.",
+					"description": "Retrieves an `Alarm Definition` by its `identifier`.\n\n The `identifier` needs to point to an existing `Alarm Definition`, otherwise this operation respond in `HTTP 404`. ",
 					"operationId": "getAlarmDefinition",
 					"parameters": [{
 						"name": "identifier",
@@ -142598,7 +143269,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 			"/service/dtm/definitions/alarms/count": { "get": {
 				"tags": ["Alarm Definitions"],
 				"summary": "Get count of Alarm Definitions",
-				"description": "Counts the collection of `Alarm Definition`s.\n\n The following rules will be applied when searching for the `Alarm Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.*",
+				"description": "Counts the collection of `Alarm Definition`s.\n\n The following rules will be applied when searching for the `Alarm Definition`s: \n\n * `identifiers`, `titles`, `tags` will be concatenated using logical AND operators\n\n * Values within a filter will be concatenated using a logical OR operator\n\n  For instance, the query filter `?identifiers=id_a,id_b&title=position` results in the following query filter:` (identifier equals id_a OR identifier equals id_b) AND title equals position `\n\n *Will be executed in context of an `Storage` tenant.* ",
 				"operationId": "countAlarmDefinitions",
 				"parameters": [
 					{
@@ -142637,11 +143308,41 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					"content": { "application/json": { "schema": { "type": "integer" } } }
 				} }
 			} },
-			"/service/dtm/assets/{assetId}/subAssets": { "get": {
+			"/service/dtm/assets/{assetId}/linkedSeries/count": { "get": {
+				"tags": ["Linked Series"],
+				"summary": "Get count of linked series for an asset",
+				"description": "Counts linked series for a given asset.\n\n Provides a count of linked series, with optional `fragment` and `series` query parameters to filter and count specific linked series. ",
+				"operationId": "countLinkedSeries",
+				"parameters": [
+					{
+						"name": "assetId",
+						"in": "path",
+						"required": true,
+						"schema": { "type": "string" }
+					},
+					{
+						"name": "fragment",
+						"in": "query",
+						"description": "A characteristic which identifies the measurement.",
+						"schema": { "type": "string" }
+					},
+					{
+						"name": "series",
+						"in": "query",
+						"description": "The specific series to search for.",
+						"schema": { "type": "string" }
+					}
+				],
+				"responses": { "200": {
+					"description": "OK",
+					"content": { "application/json": { "schema": { "type": "integer" } } }
+				} }
+			} },
+			"/service/dtm/assets/{assetId}/devices": { "get": {
 				"tags": ["Assets"],
-				"summary": "Retrieve sub-assets of an asset",
-				"description": "Retrieves sub-assets of an asset.\n\n Fetches all sub-assets of the parent asset specified by `assetId`. You can optionally apply the filter `query`.",
-				"operationId": "getSubAssets",
+				"summary": "Retrieve child devices of an asset",
+				"description": "Retrieves child devices of an asset.\n\n Fetches all child devices of the parent asset specified by `assetId`. ",
+				"operationId": "getChildDevices",
 				"parameters": [
 					{
 						"name": "assetId",
@@ -142672,22 +143373,12 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							}
 						}
 					},
-					{
-						"name": "withLinkedSeries",
-						"in": "query",
-						"description": "Indicates the resource to add the `c8y_LinkedSeries` fragment in the response.",
-						"schema": {
-							"type": "boolean",
-							"default": false
-						}
-					},
 					{
 						"name": "currentPage",
 						"in": "query",
 						"schema": {
-							"type": "integer",
-							"format": "int32",
-							"default": 1
+							"minimum": 1,
+							"type": "integer"
 						}
 					},
 					{
@@ -142702,50 +143393,26 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				],
 				"responses": { "200": {
 					"description": "OK",
-					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetList" } } }
-				} }
-			} },
-			"/service/dtm/assets/{assetId}/linkedSeries/count": { "get": {
-				"tags": ["Linked Series"],
-				"summary": "Get count of linked series for an asset",
-				"description": "Counts linked series for a given asset.\n\n Provides a count of linked series, with optional `fragment` and `series` query parameters to filter and count specific linked series.",
-				"operationId": "countLinkedSeries",
-				"parameters": [
-					{
-						"name": "assetId",
-						"in": "path",
-						"required": true,
-						"schema": { "type": "string" }
-					},
-					{
-						"name": "fragment",
-						"in": "query",
-						"description": "A characteristic which identifies the measurement.",
-						"schema": { "type": "string" }
-					},
-					{
-						"name": "series",
-						"in": "query",
-						"description": "The specific series to search for.",
-						"schema": { "type": "string" }
-					}
-				],
-				"responses": { "200": {
-					"description": "OK",
-					"content": { "application/json": { "schema": { "type": "integer" } } }
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDeviceList" } } }
 				} }
 			} },
-			"/service/dtm/assets/{assetId}/devices": { "get": {
+			"/service/dtm/assets/subAssets": { "get": {
 				"tags": ["Assets"],
-				"summary": "Retrieve child devices of an asset",
-				"description": "Retrieves child devices of an asset.\n\n Fetches all child devices of the parent asset specified by `assetId`.",
-				"operationId": "getChildDevices",
+				"summary": "Retrieve sub-assets by parent IDs",
+				"description": "Retrieves sub-assets across multiple parent assets.\n\n Fetches all direct sub-assets that are children of given parent asset IDs. ",
+				"operationId": "getSubAssetsByParents",
 				"parameters": [
 					{
-						"name": "assetId",
-						"in": "path",
+						"name": "parents",
+						"in": "query",
+						"description": "List of parent asset IDs used to scope the sub-assets query. At least one parent ID must be provided. Sub-assets that are direct children of any of the given parent assets are returned.",
 						"required": true,
-						"schema": { "type": "string" }
+						"explode": false,
+						"schema": {
+							"minItems": 1,
+							"type": "array",
+							"items": { "type": "string" }
+						}
 					},
 					{
 						"name": "query",
@@ -142770,13 +143437,48 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							}
 						}
 					},
+					{
+						"name": "withLinkedSeries",
+						"in": "query",
+						"description": "Indicates the resource to add the `c8y_LinkedSeries` fragment in the response.",
+						"schema": {
+							"type": "boolean",
+							"default": false
+						}
+					},
+					{
+						"name": "withParents",
+						"in": "query",
+						"description": "Indicates the resource to add the parent assets in the response.",
+						"schema": {
+							"type": "boolean",
+							"default": false
+						}
+					},
+					{
+						"name": "includeGroups",
+						"in": "query",
+						"description": "Indicates the resource to include assets and device groups in the response. If `false`, only assets are included.",
+						"schema": {
+							"type": "boolean",
+							"default": false
+						}
+					},
+					{
+						"name": "withChildrenCount",
+						"in": "query",
+						"description": "Indicates the resource to include the total number of child entities (sub-assets and devices) in the response.",
+						"schema": {
+							"type": "boolean",
+							"default": false
+						}
+					},
 					{
 						"name": "currentPage",
 						"in": "query",
 						"schema": {
-							"type": "integer",
-							"format": "int32",
-							"default": 1
+							"minimum": 1,
+							"type": "integer"
 						}
 					},
 					{
@@ -142791,13 +143493,13 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 				],
 				"responses": { "200": {
 					"description": "OK",
-					"content": { "application/json": { "schema": { "type": "string" } } }
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetList" } } }
 				} }
 			} },
 			"/service/dtm/assets/linkedSeries": { "get": {
 				"tags": ["Linked Series"],
 				"summary": "Retrieve linked series for all assets",
-				"description": "Retrieves linked series for all assets on your tenant.\n\n Provides a list of linked series, with a set of optional query parameters to filter for specific linked series, asset types or asset ids.",
+				"description": "Retrieves linked series for all assets on your tenant.\n\n Provides a list of linked series, with a set of optional query parameters to filter for specific linked series, asset types or asset ids. ",
 				"operationId": "getLinkedSeriesByQuery",
 				"parameters": [
 					{
@@ -142832,9 +143534,8 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 						"name": "currentPage",
 						"in": "query",
 						"schema": {
-							"type": "integer",
-							"format": "int32",
-							"default": 1
+							"minimum": 1,
+							"type": "integer"
 						}
 					},
 					{
@@ -142852,15 +143553,66 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetList" } } }
 				} }
 			} },
+			"/service/dtm/assets/linkedSeries/opposites/{deviceId}": { "get": {
+				"tags": ["Linked Series"],
+				"summary": "Get all assets linked to a specific device by its ID.",
+				"description": "The API response with the default `Accept` header `application/json` is deprecated and will be removed in a future\nversion. Please use the `Accept` header `application/vnd.com.nsn.cumulocity.linkedassetscollection+json` which offers\nbetter performance and filter parameters.",
+				"operationId": "getOppositeAssets",
+				"parameters": [
+					{
+						"name": "deviceId",
+						"in": "path",
+						"description": "the ID of the device",
+						"required": true,
+						"schema": { "type": "string" }
+					},
+					{
+						"name": "assetIds",
+						"in": "query",
+						"description": "The asset IDs to search for.",
+						"explode": false,
+						"schema": {
+							"type": "array",
+							"items": { "type": "string" }
+						}
+					},
+					{
+						"name": "fragment",
+						"in": "query",
+						"description": "A characteristic which identifies the measurement.",
+						"schema": { "type": "string" }
+					},
+					{
+						"name": "series",
+						"in": "query",
+						"description": "The specific series to search for.",
+						"schema": { "type": "string" }
+					}
+				],
+				"responses": { "200": {
+					"description": "a set of assets linked to the specified device",
+					"content": {
+						"application/vnd.com.nsn.cumulocity.linkedassetscollection+json": { "schema": {
+							"type": "array",
+							"items": { "$ref": "#/components/schemas/LinkedAsset" }
+						} },
+						"application/json": { "schema": {
+							"type": "array",
+							"items": { "$ref": "#/components/schemas/Asset" }
+						} }
+					}
+				} }
+			} },
 			"/service/dtm/assets/externalIds/{externalId}": { "get": {
 				"tags": ["Assets"],
 				"summary": "Retrieve an asset by its external ID",
-				"description": "Retrieves an Asset by its external ID of type `c8y_ExternalId`.\n\n This endpoint allows clients to look up assets using identifiers from external systems. It resolves the external ID to a ManagedObject and returns the corresponding Asset if found.",
+				"description": "Retrieves an Asset by its external ID of type `c8y_ExternalId`.\n\n This endpoint allows clients to look up assets using identifiers from external systems. It resolves the external ID to a ManagedObject and returns the corresponding Asset if found. ",
 				"operationId": "getAssetByExternalId",
 				"parameters": [
 					{
 						"name": "externalId",
 						"in": "path",
+						"description": "The external identifier of type `c8y_Asset` of the asset.",
 						"required": true,
 						"schema": { "type": "string" }
 					},
@@ -142876,7 +143628,26 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					{
 						"name": "withSubAssets",
 						"in": "query",
-						"description": "Indicates the resource to add the sub-assets in the response.",
+						"description": "**Deprecated** – use the dedicated `/assets/{assetId}/subAssets`, `/assets/externalIds/{externalId}/subAssets` or `/assets/subAssets` endpoint instead!<br>Indicates the resource to add the sub-assets in the response.",
+						"deprecated": true,
+						"schema": {
+							"type": "boolean",
+							"default": false
+						}
+					},
+					{
+						"name": "withParents",
+						"in": "query",
+						"description": "Indicates the resource to add the parent assets in the response.",
+						"schema": {
+							"type": "boolean",
+							"default": false
+						}
+					},
+					{
+						"name": "withChildrenCount",
+						"in": "query",
+						"description": "Indicates the resource to include the total number of child entities (sub-assets and devices) in the response.",
 						"schema": {
 							"type": "boolean",
 							"default": false
@@ -142888,41 +143659,148 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } }
 				} }
 			} },
+			"/service/dtm/assets/externalIds/{externalId}/subAssets": { "get": {
+				"tags": ["Assets"],
+				"summary": "Retrieve sub-assets of an asset by its external ID",
+				"description": "Retrieves direct sub-assets of the asset identified by the given external ID.\n\n Resolves the asset by its `c8y_ExternalId` and returns a paginated list of its immediate child assets. ",
+				"operationId": "getSubAssetsByExternalId",
+				"parameters": [
+					{
+						"name": "externalId",
+						"in": "path",
+						"description": "The external identifier of type `c8y_Asset` of the asset.",
+						"required": true,
+						"schema": { "type": "string" }
+					},
+					{
+						"name": "query",
+						"in": "query",
+						"description": "Use the `$filter` keyword to specify filtering criteria. Filtering can be applied to properties of the asset. Detailed information can be found within the Cumulocity core OpenAPI [here](https://cumulocity.com/api/core/#tag/Query-language).",
+						"schema": {
+							"type": "string",
+							"format": "c8y:query"
+						},
+						"examples": {
+							"Filter by name": {
+								"description": "Filter by name",
+								"value": "$filter=name eq 'Windfarm'"
+							},
+							"Filter by type": {
+								"description": "Filter by type",
+								"value": "$filter=type eq 'c8y_*'"
+							},
+							"Using orderby": {
+								"description": "Using orderby",
+								"value": "$orderby=id asc"
+							}
+						}
+					},
+					{
+						"name": "withLinkedSeries",
+						"in": "query",
+						"description": "Indicates the resource to add the `c8y_LinkedSeries` fragment in the response.",
+						"schema": {
+							"type": "boolean",
+							"default": false
+						}
+					},
+					{
+						"name": "withParents",
+						"in": "query",
+						"description": "Indicates the resource to add the parent assets in the response.",
+						"schema": {
+							"type": "boolean",
+							"default": false
+						}
+					},
+					{
+						"name": "includeGroups",
+						"in": "query",
+						"description": "Indicates the resource to include assets and device groups in the response. If `false`, only assets are included.",
+						"schema": {
+							"type": "boolean",
+							"default": false
+						}
+					},
+					{
+						"name": "withChildrenCount",
+						"in": "query",
+						"description": "Indicates the resource to include the total number of child entities (sub-assets and devices) in the response.",
+						"schema": {
+							"type": "boolean",
+							"default": false
+						}
+					},
+					{
+						"name": "currentPage",
+						"in": "query",
+						"schema": {
+							"minimum": 1,
+							"type": "integer"
+						}
+					},
+					{
+						"name": "pageSize",
+						"in": "query",
+						"schema": {
+							"maximum": 2e3,
+							"minimum": 1,
+							"type": "integer"
+						}
+					}
+				],
+				"responses": { "200": {
+					"description": "OK",
+					"content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetList" } } }
+				} }
+			} },
 			"/service/dtm/assets/count": { "get": {
 				"tags": ["Assets"],
 				"summary": "Get count of assets",
-				"description": "Counts all assets on your tenant.\n\n You can optionally apply the filters `query` and `onlyRoots`.",
+				"description": "Counts all assets on your tenant.\n\n You can optionally apply the filters `query`, `onlyRoots` and `includeGroups`. ",
 				"operationId": "countAssets",
-				"parameters": [{
-					"name": "query",
-					"in": "query",
-					"description": "Use the `$filter` keyword to specify filtering criteria. Filtering can be applied to properties of the asset. Detailed information can be found within the Cumulocity core OpenAPI [here](https://cumulocity.com/api/core/#tag/Query-language).",
-					"schema": {
-						"type": "string",
-						"format": "c8y:query"
-					},
-					"examples": {
-						"Filter by name": {
-							"description": "Filter by name",
-							"value": "$filter=name eq 'Windfarm'"
-						},
-						"Filter by type": {
-							"description": "Filter by type",
-							"value": "$filter=type eq 'c8y_*'"
+				"parameters": [
+					{
+						"name": "query",
+						"in": "query",
+						"description": "Use the `$filter` keyword to specify filtering criteria. Filtering can be applied to properties of the asset. Detailed information can be found within the Cumulocity core OpenAPI [here](https://cumulocity.com/api/core/#tag/Query-language).",
+						"schema": {
+							"type": "string",
+							"format": "c8y:query"
 						},
-						"Using orderby": {
-							"description": "Using orderby",
-							"value": "$orderby=id asc"
+						"examples": {
+							"Filter by name": {
+								"description": "Filter by name",
+								"value": "$filter=name eq 'Windfarm'"
+							},
+							"Filter by type": {
+								"description": "Filter by type",
+								"value": "$filter=type eq 'c8y_*'"
+							},
+							"Using orderby": {
+								"description": "Using orderby",
+								"value": "$orderby=id asc"
+							}
+						}
+					},
+					{
+						"name": "onlyRoots",
+						"in": "query",
+						"schema": {
+							"type": "boolean",
+							"default": false
+						}
+					},
+					{
+						"name": "includeGroups",
+						"in": "query",
+						"description": "Indicates the resource to include assets and device groups in the response. If `false`, only assets are included.",
+						"schema": {
+							"type": "boolean",
+							"default": false
 						}
 					}
-				}, {
-					"name": "onlyRoots",
-					"in": "query",
-					"schema": {
-						"type": "boolean",
-						"default": false
-					}
-				}],
+				],
 				"responses": { "200": {
 					"description": "OK",
 					"content": { "application/json": { "schema": { "type": "integer" } } }
@@ -142949,7 +143827,11 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							"pattern": "^(?:[A-Za-z0-9](?:\\s*[-\\w:.!])*\\s*)?$",
 							"type": "string"
 						},
-						"description": { "type": "string" }
+						"description": { "type": "string" },
+						"additionalProperties": {
+							"type": "boolean",
+							"writeOnly": true
+						}
 					},
 					"example": {
 						"title": "Position",
@@ -143010,12 +143892,20 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							}
 						},
 						"c8y_AvailableActions": { "$ref": "#/components/schemas/AvailableActions" },
+						"c8y_SharedDefinition": { "$ref": "#/components/schemas/SharedDefinition" },
 						"c8y_Origin": {
 							"type": "string",
 							"description": "Specifies the origin of this Property Definition and identifies the owning component. If the value is <code>library</code>, the Property Definition is system-defined and read-only."
 						}
 					}
 				},
+				"SharedDefinition": {
+					"type": "object",
+					"properties": { "self": { "type": "string" } },
+					"additionalProperties": false,
+					"description": "Indicates that this definition is maintained on the enterprise tenant and is shared on its subtenants.",
+					"readOnly": true
+				},
 				"AllowedPropertyDefinition": {
 					"required": ["identifier"],
 					"type": "object",
@@ -143072,7 +143962,8 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							} },
 							"additionalProperties": false
 						},
-						"c8y_AvailableActions": { "$ref": "#/components/schemas/AvailableActions" }
+						"c8y_AvailableActions": { "$ref": "#/components/schemas/AvailableActions" },
+						"c8y_SharedDefinition": { "$ref": "#/components/schemas/SharedDefinition" }
 					}
 				},
 				"EventDefinition": {
@@ -143105,6 +143996,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							}
 						},
 						"c8y_AvailableActions": { "$ref": "#/components/schemas/AvailableActions" },
+						"c8y_SharedDefinition": { "$ref": "#/components/schemas/SharedDefinition" },
 						"composition": {
 							"type": "object",
 							"properties": { "allowedProperties": {
@@ -143146,6 +144038,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							}
 						},
 						"c8y_AvailableActions": { "$ref": "#/components/schemas/AvailableActions" },
+						"c8y_SharedDefinition": { "$ref": "#/components/schemas/SharedDefinition" },
 						"composition": {
 							"type": "object",
 							"properties": {
@@ -143202,6 +144095,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							}
 						},
 						"c8y_AvailableActions": { "$ref": "#/components/schemas/AvailableActions" },
+						"c8y_SharedDefinition": { "$ref": "#/components/schemas/SharedDefinition" },
 						"composition": {
 							"type": "object",
 							"properties": { "allowedProperties": {
@@ -143246,6 +144140,11 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							"readOnly": true,
 							"items": { "$ref": "#/components/schemas/Asset" }
 						},
+						"assetParents": {
+							"type": "array",
+							"readOnly": true,
+							"items": { "$ref": "#/components/schemas/Asset" }
+						},
 						"c8y_LinkedSeries": {
 							"type": "array",
 							"items": { "$ref": "#/components/schemas/LinkedSeries" }
@@ -143256,7 +144155,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 						},
 						"c8y_LatestMeasurements": { "$ref": "#/components/schemas/LatestMeasurements" },
 						"c8y_ExternalId": {
-							"maxLength": 2147483647,
+							"maxLength": 680,
 							"minLength": 1,
 							"type": "string",
 							"description": "Represents an external identifier used to reference this asset in external systems. When set, an identity of type 'c8y_Asset' is created for this asset with the value of this property."
@@ -143264,6 +144163,11 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 						"c8y_ExternalAsset": {
 							"type": "object",
 							"description": "Represents Assets synchronized from external systems into Cumulocity IoT. The fragment allows storing free-form metadata relevant to external systems."
+						},
+						"assignedChildrenCount": {
+							"type": "integer",
+							"format": "int32",
+							"readOnly": true
 						}
 					}
 				},
@@ -143343,6 +144247,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 							"example": "T"
 						},
 						"id": {
+							"pattern": "^(?!\\s*$).+$",
 							"type": "string",
 							"example": "9688123"
 						},
@@ -143357,6 +144262,51 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					},
 					"additionalProperties": false
 				},
+				"AssetReference": {
+					"type": "object",
+					"properties": {
+						"fragment": {
+							"type": "string",
+							"example": "c8y_Temperature"
+						},
+						"series": {
+							"type": "string",
+							"example": "T"
+						},
+						"id": {
+							"type": "string",
+							"example": "9688123"
+						},
+						"label": {
+							"type": "string",
+							"example": "Room temperature"
+						}
+					},
+					"additionalProperties": false
+				},
+				"LinkedAsset": {
+					"type": "object",
+					"properties": {
+						"fragment": {
+							"type": "string",
+							"example": "c8y_Temperature"
+						},
+						"series": {
+							"type": "string",
+							"example": "T"
+						},
+						"type": {
+							"type": "string",
+							"example": "c8y_TemperatureMeasurement"
+						},
+						"name": {
+							"type": "string",
+							"example": "MyTemperatureMeasurement"
+						},
+						"asset": { "$ref": "#/components/schemas/AssetReference" }
+					},
+					"additionalProperties": false
+				},
 				"PageStatistics": {
 					"required": [
 						"currentPage",
@@ -143392,7 +144342,7 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					"additionalProperties": false
 				},
 				"PaginatedDefinitionList": {
-					"required": ["definitions", "statistics"],
+					"required": ["statistics"],
 					"type": "object",
 					"properties": {
 						"self": {
@@ -143497,6 +144447,71 @@ const BUNDLED_SERVICE_SPECS = Object.freeze([{
 					},
 					"additionalProperties": false
 				},
+				"Device": {
+					"title": "Device",
+					"required": ["id"],
+					"type": "object",
+					"properties": {
+						"creationTime": {
+							"type": "string",
+							"readOnly": true,
+							"example": "2017-12-12T22:09:06.881+01:00"
+						},
+						"lastUpdated": {
+							"type": "string",
+							"readOnly": true,
+							"example": "2018-07-19T12:01:50.731Z"
+						},
+						"id": {
+							"type": "string",
+							"readOnly": true,
+							"example": "4512412"
+						},
+						"type": {
+							"type": "string",
+							"example": "c8y_TemperatureSensor"
+						},
+						"name": {
+							"type": "string",
+							"example": "TemperatureSensor"
+						},
+						"owner": { "type": "string" },
+						"c8y_LatestMeasurements": { "$ref": "#/components/schemas/LatestMeasurements" }
+					}
+				},
+				"PaginatedDeviceList": {
+					"required": ["devices", "statistics"],
+					"type": "object",
+					"properties": {
+						"self": {
+							"title": "SelfURL",
+							"type": "string",
+							"description": "A URL linking to this resource.",
+							"format": "uri",
+							"readOnly": true
+						},
+						"next": {
+							"title": "NextPageURL",
+							"type": "string",
+							"description": "A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] to a potential next page.",
+							"format": "uri",
+							"readOnly": true
+						},
+						"prev": {
+							"title": "PreviousPageURL",
+							"type": "string",
+							"description": "A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] to a potential previous page.",
+							"format": "uri",
+							"readOnly": true
+						},
+						"devices": {
+							"type": "array",
+							"items": { "$ref": "#/components/schemas/Device" }
+						},
+						"statistics": { "$ref": "#/components/schemas/PageStatistics" }
+					},
+					"additionalProperties": false
+				},
 				"AllowedSubAssetDefinition": {
 					"required": ["identifier"],
 					"type": "object",
@@ -143898,6 +144913,10 @@ runMain(defineCommand({
 		"no-mcp": {
 			type: "string",
 			description: "Disable MCP wrapping: pass \"*\" (or no value) for all services, or a contextPath. Can be repeated. Opted-out services fall back to their OpenAPI spec."
+		},
+		"mcp-server": {
+			type: "string",
+			description: "External MCP server to expose as a codemode namespace, as JSON: '{\"name\":\"github\",\"url\":\"https://api.githubcopilot.com/mcp/\",\"token\":\"…\"}'. Can be repeated."
 		}
 	},
 	setup: () => {
@@ -143922,6 +144941,10 @@ runMain(defineCommand({
 		const rawNoMcp = args["no-mcp"];
 		const noMcp = parseNoMcp(Array.isArray(rawNoMcp) ? rawNoMcp : rawNoMcp !== void 0 ? [rawNoMcp] : []);
 		if (noMcp.all || noMcp.contextPaths.size > 0) consola.info(`MCP wrapping disabled for: ${noMcp.all ? "all services" : [...noMcp.contextPaths].join(", ")}`);
+		const rawMcpServers = args["mcp-server"];
+		const { servers: externalMcpServers, failedEntries: failedMcpServers } = parseExternalMcpServers((Array.isArray(rawMcpServers) ? rawMcpServers : rawMcpServers ? [rawMcpServers] : []).filter((v) => typeof v === "string" && v.length > 0));
+		if (failedMcpServers.length > 0) throw new Error(["One or more --mcp-server flags could not be parsed:", ...failedMcpServers.map((e) => `- ${e.entry}: ${e.reason}`)].join("\n"));
+		if (externalMcpServers.length > 0) consola.info(`External MCP namespaces: ${externalMcpServers.map((s) => `${s.name} (${s.url})`).join(", ")}`);
 		const activeTenant = readActiveTenantUrl();
 		if (activeTenant) try {
 			const tenantCtx = await setCliTenantContext(activeTenant);
@@ -143946,6 +144969,7 @@ runMain(defineCommand({
 			restrictions,
 			allowRules: parsedAllowRules,
 			noMcp,
+			externalMcpServers,
 			specs: active?.specs ?? getBundledOnlyCapabilities(),
 			auth: active ? {
 				tenantUrl: active.tenantUrl,