elastic · kibanamachine · Apr 20, 2026 · Apr 20, 2026
@@ -12,13 +12,44 @@ import { schema } from '@kbn/config-schema';
 
 export const asCodeMetaSchema = schema.object(
   {
-    created_at: schema.maybe(schema.string()),
-    created_by: schema.maybe(schema.string()),
-    managed: schema.maybe(schema.boolean()),
-    owner: schema.maybe(schema.string()),
-    updated_at: schema.maybe(schema.string()),
-    updated_by: schema.maybe(schema.string()),
-    version: schema.maybe(schema.string()),
+    created_at: schema.maybe(
+      schema.string({
+        meta: { description: 'Timestamp when the object was created (ISO 8601).' },
+      })
+    ),
+    created_by: schema.maybe(
+      schema.string({
+        meta: { description: 'User profile ID of the user who created the object.' },
+      })
+    ),
+    managed: schema.maybe(
+      schema.boolean({
+        meta: {
+          description:
+            'When `true`, the object is managed by Kibana and cannot be edited by users.',
+        },
+      })
+    ),
+    owner: schema.maybe(
+      schema.string({
+        meta: { description: 'Identifier of the plugin or team that owns this object.' },
+      })
+    ),
+    updated_at: schema.maybe(
+      schema.string({
+        meta: { description: 'Timestamp when the object was last updated (ISO 8601).' },
+      })
+    ),
+    updated_by: schema.maybe(
+      schema.string({
+        meta: { description: 'User profile ID of the user who last updated the object.' },
+      })
+    ),
+    version: schema.maybe(
+      schema.string({
+        meta: { description: 'Internal version identifier for optimistic concurrency control.' },
+      })
+    ),
   },
   {
     meta: {

@@ -33,11 +33,16 @@ export const registerLensVisualizationsCreateAPIRoute: RegisterAPIRouteFn = (
     path: LENS_VIS_API_PATH,
     access: LENS_API_ACCESS,
     summary: 'Create visualization',
-    description: 'Create a new visualization.',
+    description: [
+      'Creates a Lens visualization and saves it to the library.',
+      '',
+      'ES|QL visualizations cannot be created through this endpoint.',
+    ].join('\n'),
     options: {
       tags: [LENS_API_TAG],
       availability: {
         stability: 'experimental',
+        since: '9.4.0',
       },
     },
     security: {

@@ -25,11 +25,13 @@ export const registerLensVisualizationsDeleteAPIRoute: RegisterAPIRouteFn = (
     path: `${LENS_VIS_API_PATH}/{id}`,
     access: LENS_API_ACCESS,
     summary: 'Delete visualization',
-    description: 'Delete a visualization by id.',
+    description:
+      'Permanently deletes a Lens visualization. If the visualization is referenced by a dashboard panel, the panel shows an error after deletion.',
     options: {
       tags: [LENS_API_TAG],
       availability: {
         stability: 'experimental',
+        since: '9.4.0',
       },
     },
     security: {

@@ -29,11 +29,12 @@ export const registerLensVisualizationsGetAPIRoute: RegisterAPIRouteFn = (
     path: `${LENS_VIS_API_PATH}/{id}`,
     access: LENS_API_ACCESS,
     summary: 'Get visualization',
-    description: 'Get a visualization from id.',
+    description: 'Returns a single Lens visualization by its ID.',
     options: {
       tags: [LENS_API_TAG],
       availability: {
         stability: 'experimental',
+        since: '9.4.0',
       },
     },
     security: {

@@ -11,7 +11,7 @@ export const lensDeleteRequestParamsSchema = schema.object(
   {
     id: schema.string({
       meta: {
-        description: 'The id of a visualization.',
+        description: 'The visualization identifier, as returned by the create or search endpoints.',
       },
     }),
   },

@@ -13,7 +13,7 @@ export const lensGetRequestParamsSchema = schema.object(
   {
     id: schema.string({
       meta: {
-        description: 'The id of a visualization.',
+        description: 'The visualization identifier, as returned by the create or search endpoints.',
       },
     }),
   },

@@ -17,20 +17,20 @@ export const lensSearchRequestQuerySchema = schema.object({
   query: schema.maybe(
     schema.string({
       meta: {
-        description: 'The text to search for Lens visualizations',
+        description: 'Text to match against `search_fields`.',
       },
     })
   ),
   page: schema.number({
     meta: {
-      description: 'Specifies the current page number of the paginated result.',
+      description: 'Page number.',
     },
     min: 1,
     defaultValue: 1,
   }),
   per_page: schema.number({
     meta: {
-      description: 'Maximum number of Lens visualizations included in a single response',
+      description: 'Results per page.',
     },
     defaultValue: 20,
     min: 1,
@@ -42,7 +42,9 @@ const lensSearchResponseMetaSchema = schema.object(
   {
     page: searchOptionsSchemas.page,
     per_page: searchOptionsSchemas.perPage,
-    total: schema.number(), // TODO use shared definition
+    total: schema.number({
+      meta: { description: 'Total number of matching visualizations.' },
+    }),
   },
   { unknowns: 'forbid' }
 );

@@ -14,7 +14,7 @@ export const lensUpdateRequestParamsSchema = schema.object(
   {
     id: schema.string({
       meta: {
-        description: 'The id of a visualization.',
+        description: 'The visualization identifier, as returned by the create or search endpoints.',
       },
     }),
   },

@@ -28,11 +28,13 @@ export const registerLensVisualizationsSearchAPIRoute: RegisterAPIRouteFn = (
     path: LENS_VIS_API_PATH,
     access: LENS_API_ACCESS,
     summary: 'Search visualizations',
-    description: 'Get list of visualizations.',
+    description:
+      'Returns a paginated list of Lens visualizations matching the optional `query` text.',
     options: {
       tags: [LENS_API_TAG],
       availability: {
         stability: 'experimental',
+        since: '9.4.0',
       },
     },
     security: {

@@ -34,13 +34,20 @@ export const registerLensVisualizationsUpdateAPIRoute: RegisterAPIRouteFn = (
   const updateRoute = router.put({
     path: `${LENS_VIS_API_PATH}/{id}`,
     access: LENS_API_ACCESS,
-    summary: 'Create or update visualization',
-    description:
-      'Create or update a visualization with the given id. When no visualization exists for the id, one is created.',
+    summary: 'Update visualization',
+    description: [
+      'Replaces the full configuration of an existing Lens visualization. Partial updates are not supported.',
+      'To make incremental changes, retrieve the visualization first, modify the fields you need, then send the complete object back.',
+      '',
+      'If no visualization exists with the specified ID, a new one is created.',
+      '',
+      'ES|QL visualizations cannot be updated through this endpoint.',
+    ].join('\n'),
     options: {
       tags: [LENS_API_TAG],
       availability: {
         stability: 'experimental',
+        since: '9.4.0',
       },
     },
     security: {
-Original file line number
+Diff line change
@@ Expand Up / @@ -11,7 +11,7 @@ export const lensDeleteRequestParamsSchema = schema.object( @@
       {
         id: schema.string({
           meta: {
-            description: 'The id of a visualization.',
+            description: 'The visualization identifier, as returned by the create or search endpoints.',
           },
         }),
       },
@@ Expand Down @@