update descriptions for various endpoints

Author: Leopold-Cramer

dataset/src/main/openapi/dataset.yaml

@@ -20,11 +20,11 @@ paths:
     parameters:
       - $ref: '#/components/parameters/organizationId'
       - $ref: '#/components/parameters/workspaceId'
-    description: Create a dataset
     post:
       operationId: createDataset
       tags:
         - dataset
+      description: "Create a new dataset in the workspace. Required fields: name. The dataset is initialized with empty data and can be populated through dataset parts. Creator becomes admin."
       summary: Create a Dataset
       requestBody:
         content:
@@ -71,7 +71,7 @@ paths:
         - $ref: '#/components/parameters/size'
       tags:
         - dataset
-      description: List all datasets
+      description: "Retrieve a paginated list of all datasets in the specified workspace. Supports pagination via 'page' and 'size' query parameters. Returns datasets based on user permissions."
       summary: Retrieve a list of defined Dataset
       responses:
         "200":
@@ -166,7 +166,7 @@ paths:
       operationId: getDataset
       tags:
         - dataset
-      description: Retrieve a dataset
+      description: "Retrieve complete information about a specific dataset including metadata, source configuration, security settings, and associated dataset parts summary."
       summary: Retrieve a Dataset
       responses:
         "200":
@@ -192,7 +192,7 @@ paths:
       operationId: updateDataset
       tags:
         - dataset
-      description: Update a dataset
+      description: "Update dataset metadata (name, description, tags). Note: Some fields cannot be modified after creation. Returns the updated dataset."
       summary: Update a Dataset
       requestBody:
         content:
@@ -235,7 +235,7 @@ paths:
       operationId: deleteDataset
       tags:
         - dataset
-      description: Delete a dataset
+      description: "Permanently delete a dataset and all its data parts. This operation cannot be undone. Returns 204 on success, 404 if not found, 409 if dataset is in use by runners."
       summary: Delete a Dataset
       responses:
         "204":
@@ -411,6 +411,7 @@ paths:
       operationId: deleteDatasetAccessControl
       tags:
         - dataset
+      description: "Remove a user or group's access to a dataset. Cannot remove the last administrator - at least one admin must remain."
       summary: Remove the specified access from the given Dataset
       responses:
         "204":
@@ -460,9 +461,9 @@ paths:
       operationId: createDatasetPart
       tags:
         - dataset
+      description: "Create a new data part within a dataset. Specify type as 'FILE' for file uploads or 'DB' for database queries. Returns the created part with generated ID."
       summary: Create a data part of a Dataset
       requestBody:
-        description: New Dataset part to create.
         content:
           multipart/form-data:
             schema:
@@ -507,6 +508,7 @@ paths:
         - $ref: '#/components/parameters/size'
       tags:
         - dataset
+      description: "Retrieve all data parts associated with a dataset. Parts can be of type FILE (uploaded files) or DB (database connections). Returns part metadata, type, and status."
       summary: Retrieve all dataset parts of a Dataset
       responses:
         "200":
@@ -759,6 +761,7 @@ paths:
       operationId: queryData
       tags:
         - dataset
+      description: "Execute a SQL or DSL query against a database-type dataset part. The query parameter is required. Results are returned as JSON. Only available for parts with type=DB."
       summary: |
         Query data of a Dataset part.
         This endpoint is only available for dataset parts that support queries (type == DB).
@@ -789,6 +792,7 @@ paths:
       operationId: downloadDatasetPart
       tags:
         - dataset
+      description: "Download the file content from a FILE-type dataset part. Returns the file as a binary stream with appropriate Content-Type. Not available for DB-type parts."
       summary: Download data from a dataset part
       responses:
         "200":

doc/Apis/DatasetApi.md

@@ -33,6 +33,8 @@ All URIs are relative to *http://localhost:8080*
 
 Create a Dataset
 
+    Create a new dataset in the workspace. Required fields: name. The dataset is initialized with empty data and can be populated through dataset parts. Creator becomes admin.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -89,6 +91,8 @@ Add a control access to the Dataset
 
 Create a data part of a Dataset
 
+    Create a new data part within a dataset. Specify type as 'FILE' for file uploads or 'DB' for database queries. Returns the created part with generated ID.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -118,7 +122,7 @@ Create a data part of a Dataset
 
 Delete a Dataset
 
-    Delete a dataset
+    Permanently delete a dataset and all its data parts. This operation cannot be undone. Returns 204 on success, 404 if not found, 409 if dataset is in use by runners.
 
 ### Parameters
 
@@ -147,6 +151,8 @@ null (empty response body)
 
 Remove the specified access from the given Dataset
 
+    Remove a user or group's access to a dataset. Cannot remove the last administrator - at least one admin must remain.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -205,6 +211,8 @@ null (empty response body)
 
 Download data from a dataset part
 
+    Download the file content from a FILE-type dataset part. Returns the file as a binary stream with appropriate Content-Type. Not available for DB-type parts.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -233,7 +241,7 @@ Download data from a dataset part
 
 Retrieve a Dataset
 
-    Retrieve a dataset
+    Retrieve complete information about a specific dataset including metadata, source configuration, security settings, and associated dataset parts summary.
 
 ### Parameters
 
@@ -318,6 +326,8 @@ Retrieve a data part of a Dataset
 
 Retrieve all dataset parts of a Dataset
 
+    Retrieve all data parts associated with a dataset. Parts can be of type FILE (uploaded files) or DB (database connections). Returns part metadata, type, and status.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -374,7 +384,7 @@ Get the Dataset security users list
 
 Retrieve a list of defined Dataset
 
-    List all datasets
+    Retrieve a paginated list of all datasets in the specified workspace. Supports pagination via 'page' and 'size' query parameters. Returns datasets based on user permissions.
 
 ### Parameters
 
@@ -404,6 +414,8 @@ Retrieve a list of defined Dataset
 
 Query data of a Dataset part. This endpoint is only available for dataset parts that support queries (type == DB). 
 
+    Execute a SQL or DSL query against a database-type dataset part. The query parameter is required. Results are returned as JSON. Only available for parts with type=DB.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -531,7 +543,7 @@ Search Datasets by tags
 
 Update a Dataset
 
-    Update a dataset
+    Update dataset metadata (name, description, tags). Note: Some fields cannot be modified after creation. Returns the updated dataset.
 
 ### Parameters
 

doc/Apis/MetaApi.md

@@ -13,6 +13,8 @@ All URIs are relative to *http://localhost:8080*
 
 Get various information about the API
 
+    Retrieve API version information, build details, and platform configuration. Useful for debugging and compatibility checks.
+
 ### Parameters
 This endpoint does not need any parameter.
 

doc/Apis/OrganizationApi.md

@@ -26,11 +26,13 @@ All URIs are relative to *http://localhost:8080*
 
 Create a new organization
 
+    Create a new organization. Required: name. Optional: security configuration. The creating user automatically becomes an administrator.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
 |------------- | ------------- | ------------- | -------------|
-| **OrganizationCreateRequest** | [**OrganizationCreateRequest**](../Models/OrganizationCreateRequest.md)| The Organization to create | |
+| **OrganizationCreateRequest** | [**OrganizationCreateRequest**](../Models/OrganizationCreateRequest.md)|  | |
 
 ### Return type
 
@@ -51,6 +53,8 @@ Create a new organization
 
 Add a control access to the Organization
 
+    Grant access to an organization for a user or group. Valid roles: viewer, editor, admin.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -77,6 +81,8 @@ Add a control access to the Organization
 
 Delete an organization
 
+    Permanently delete an organization. Requires all workspaces within the organization to be deleted first. This operation cannot be undone.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -128,6 +134,8 @@ null (empty response body)
 
 Get the details of an Organization
 
+    Retrieve detailed information about an organization including name, creation info, update history, and security configuration.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -255,6 +263,8 @@ Get the Organization security users list
 
 List all Organizations
 
+    Retrieve a paginated list of all organizations the authenticated user has permission to view. Use 'page' and 'size' query parameters for pagination.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |

doc/Apis/RunApi.md

@@ -45,6 +45,8 @@ null (empty response body)
 
 Get the details of a run
 
+    Retrieve detailed information about a specific run including state, parameters used, dataset list, execution timestamps, and container configuration.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -73,6 +75,8 @@ Get the details of a run
 
 get the logs for the Run
 
+    Retrieve execution logs for a run as plain text. Logs are aggregated from all containers. May be truncated for long-running simulations.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -101,6 +105,8 @@ get the logs for the Run
 
 get the status for the Run
 
+    Retrieve detailed execution status of a run including workflow phase, progress, individual node states, and estimated completion time.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -129,6 +135,8 @@ get the status for the Run
 
 get the list of Runs for the Runner
 
+    Retrieve a paginated list of all runs for a specific runner, ordered by creation time (newest first). Includes run state, timestamps, and basic metadata.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |

doc/Apis/RunnerApi.md

@@ -27,6 +27,8 @@ All URIs are relative to *http://localhost:8080*
 
 Create a new Runner
 
+    Create a new runner for executing simulations. Required: name, solutionId, runTemplateId. Use parentId to create a child runner that inherits configuration from a parent.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -54,6 +56,8 @@ Create a new Runner
 
 Add a control access to the Runner
 
+    Grant access to a runner for a user or group. Valid roles: viewer, editor, validator (can validate runs), admin.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -82,6 +86,8 @@ Add a control access to the Runner
 
 Delete a runner
 
+    Delete a runner. Cannot delete while runs are in progress. Note: Child runners that reference this runner are not deleted automatically.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -137,6 +143,8 @@ null (empty response body)
 
 Get the details of a runner
 
+    Retrieve detailed information about a runner including configuration, parameter values, dataset associations, last run status, and validation state.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -274,6 +282,8 @@ Get the Runner security users list
 
 List all Runners
 
+    Retrieve a paginated list of all runners in a workspace. Includes master runners and child runners with their current status and configuration.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -302,6 +312,8 @@ List all Runners
 
 Start a run with runner parameters
 
+    Start a new simulation run using the runner's current configuration. Returns immediately with a run ID. The run executes asynchronously - use the run status endpoint to monitor progress.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -329,6 +341,8 @@ Start a run with runner parameters
 
 Stop the last run
 
+    Stop the currently executing run for this runner. Only affects the most recent run. The stop operation is asynchronous - the run may continue briefly before stopping.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |

doc/Apis/SolutionApi.md

@@ -39,6 +39,8 @@ All URIs are relative to *http://localhost:8080*
 
 Create a new solution
 
+    Create a new solution with optional run templates and parameter definitions. Required: key (unique identifier), name. The solution key must be unique within the organization.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -65,6 +67,8 @@ Create a new solution
 
 Create solution access control
 
+    Grant access to a dataset for a user or group. Required: identity id and role. Valid roles: viewer, editor, admin. Returns 400 if user already has access.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -334,6 +338,8 @@ Retrieve a solution run templates
 
 Get the details of a solution
 
+    Retrieve detailed information about a solution including run templates, parameters, parameter groups, and security configuration.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |
@@ -571,6 +577,8 @@ List solution security users
 
 List all Solutions
 
+    Retrieve a paginated list of all solutions in an organization that the user has permission to view.
+
 ### Parameters
 
 |Name | Type | Description  | Notes |