{
	"openapi": "3.0.0",
	"info": {
		"title": "SIMULATOR OPENAPI REST-ful-API Reference",
		"version": "2025.20.0",
		"description": "\n### Introduction\nThis is the [OpenAPI 3.0](https://swagger.io/specification/) documentation\nof the [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)-ful SIMULATOR OPENAPI API.\n\n### Cross-Origin Resource Sharing\nThis API features Cross-Origin Resource Sharing (CORS) implemented in\ncompliance with [W3C spec](https://www.w3.org/TR/cors/), which allows\ncross-domain communication from the browser. All responses have a wildcard\nsame-origin header which makes the API completely accessible.\n\n### Authentication\nSIMULATOR OPENAPI offers following forms of authentication:\n- Bearer Token (JWT)\n- API Key\n\n### Error Handling\nThis API uses HTTP status codes equal or above 400 to indicate errors. Error\ndetails are generated in compliance with [RFC 7807 - \"Problem Details for HTTP APIs\"](https://tools.ietf.org/html/rfc7807).\n\nEvery error response contains a traceId, which should be provided to the SIMULATOR OPENAPI Technical Support when reporting an error.\n",
		"contact": {
			"name": "Cognigy Technical Support",
			"url": "https://www.cognigy.com",
			"email": "support@cognigy.com"
		},
		"license": {
			"name": "Cognigy Proprietary License"
		}
	},
	"components": {
		"securitySchemes": {
			"bearerAuth": {
				"type": "http",
				"scheme": "bearer",
				"bearerFormat": "JWT",
				"description": "JWT Bearer Token for authentication"
			},
			"apiKeyAuth": {
				"type": "apiKey",
				"in": "header",
				"name": "X-API-Key",
				"description": "API Key for authentication"
			}
		}
	},
	"security": [
		{
			"bearerAuth": []
		},
		{
			"apiKeyAuth": []
		}
	],
	"externalDocs": {
		"description": "SIMULATOR OPENAPI Documentation",
		"url": "https://docs.cognigy.com/docs/service-testing/"
	},
	"tags": [
		{
			"name": "Simulations",
			"description": "Simulation management operations - Create, read, update, and delete simulations"
		}
	],
	"paths": {
		"/simulations": {
			"get": {
				"operationId": "getSimulations",
				"summary": "Get all scenarios",
				"description": "Retrieve a paginated list of scenarios for the authenticated user's organization and project.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"name": "filter",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Filter criteria for searching scenarios"
					},
					{
						"name": "limit",
						"in": "query",
						"required": false,
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20
						},
						"description": "Number of items to return per page"
					},
					{
						"name": "skip",
						"in": "query",
						"required": false,
						"schema": {
							"type": "integer",
							"minimum": 0,
							"default": 0
						},
						"description": "Number of items to skip"
					},
					{
						"name": "sort",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Sort order (e.g., 'name:asc', 'createdAt:desc')"
					},
					{
						"in": "query",
						"name": "next",
						"schema": {
							"type": "string"
						},
						"description": "Pagination cursor for next page"
					},
					{
						"in": "query",
						"name": "previous",
						"schema": {
							"type": "string"
						},
						"description": "Pagination cursor for previous page"
					},
					{
						"in": "query",
						"name": "includeUpcomingSchedule",
						"required": false,
						"schema": {
							"type": "boolean",
							"default": false
						},
						"description": "When `true`, each scenario in the response is enriched with the `nextScheduledRun` of its soonest upcoming enabled schedule (or `null` if no upcoming schedule exists). Any value other than the literal `true` is treated as false and the field is omitted.\n"
					}
				],
				"responses": {
					"200": {
						"description": "List of scenarios retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": {
											"type": "array",
											"items": {
												"type": "object",
												"properties": {
													"id": {
														"type": "string",
														"description": "Unique identifier for the scenario"
													},
													"referenceId": {
														"type": "string",
														"description": "Reference ID for the scenario"
													},
													"name": {
														"type": "string",
														"description": "Name of the scenario"
													},
													"persona": {
														"type": "string",
														"description": "Persona description"
													},
													"personaName": {
														"type": "string",
														"description": "Name of the persona"
													},
													"mission": {
														"type": "string",
														"description": "Mission description"
													},
													"successCriteria": {
														"type": "array",
														"description": "List of success criteria (structured objects)",
														"items": {
															"type": "object",
															"properties": {
																"type": {
																	"type": "string",
																	"description": "Success criterion type"
																},
																"params": {
																	"type": "object",
																	"description": "Success criterion parameters"
																}
															},
															"required": [
																"type",
																"params"
															]
														}
													},
													"maxTurns": {
														"type": "integer",
														"description": "Maximum number of turns"
													},
													"timeout": {
														"type": "integer",
														"description": "Timeout in seconds"
													},
													"aiAgentReferenceId": {
														"type": "string",
														"description": "Reference ID of the AI Agent"
													},
													"aiAgentId": {
														"type": "string",
														"description": "Database ID of the AI Agent"
													},
													"flowReferenceId": {
														"type": "string",
														"description": "Reference ID of the Flow"
													},
													"flowId": {
														"type": "string",
														"description": "Database ID of the Flow"
													},
													"jobNodeId": {
														"type": "string",
														"description": "Job Node ID"
													},
													"organisationReference": {
														"type": "string",
														"description": "Organization reference"
													},
													"projectReference": {
														"type": "string",
														"description": "Project reference"
													},
													"createdAt": {
														"type": "integer",
														"format": "int64",
														"description": "Creation timestamp"
													},
													"createdBy": {
														"type": "string",
														"description": "User who created the scenario"
													},
													"updatedAt": {
														"type": "integer",
														"format": "int64",
														"description": "Last update timestamp"
													},
													"updatedBy": {
														"type": "string",
														"description": "User who last updated the scenario"
													},
													"lastChanged": {
														"type": "integer",
														"format": "int64",
														"description": "Last change timestamp"
													},
													"lastChangedBy": {
														"type": "string",
														"description": "User who made the last change"
													},
													"nextScheduledRun": {
														"type": "string",
														"format": "date-time",
														"nullable": true,
														"description": "Present when `includeUpcomingSchedule=true`. Set to the ISO timestamp of the soonest upcoming enabled schedule, or `null` when no upcoming schedule exists for this scenario. Absent entirely when the flag is not requested. The frontend uses the presence (not the value) of this field to decide whether the list response is enriched and the per-row scheduler call can be skipped.\n"
													}
												},
												"required": [
													"id",
													"referenceId",
													"name",
													"persona",
													"personaName",
													"mission",
													"successCriteria",
													"organisationReference",
													"projectReference",
													"createdAt",
													"createdBy",
													"lastChanged",
													"lastChangedBy"
												]
											},
											"description": "Array of scenario objects"
										},
										"pagination": {
											"type": "object",
											"properties": {
												"limit": {
													"type": "integer",
													"description": "Number of items per page"
												},
												"skip": {
													"type": "integer",
													"description": "Number of items skipped"
												},
												"total": {
													"type": "integer",
													"description": "Total number of items"
												},
												"hasNext": {
													"type": "boolean",
													"description": "Whether there are more items"
												},
												"hasPrevious": {
													"type": "boolean",
													"description": "Whether there are previous items"
												},
												"next": {
													"type": "string",
													"nullable": true,
													"description": "Cursor for next page"
												},
												"previous": {
													"type": "string",
													"nullable": true,
													"description": "Cursor for previous page"
												}
											},
											"required": [
												"limit",
												"skip",
												"total",
												"hasNext",
												"hasPrevious"
											]
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			},
			"post": {
				"operationId": "createSimulation",
				"summary": "Create scenario",
				"description": "Create a scenario with the provided configuration.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"projectReference": {
										"type": "string",
										"description": "Project reference (required in body)"
									},
									"name": {
										"type": "string",
										"description": "Name of the scenario"
									},
									"persona": {
										"type": "string",
										"description": "Persona description"
									},
									"personaName": {
										"type": "string",
										"description": "Name of the persona"
									},
									"mission": {
										"type": "string",
										"description": "Mission description"
									},
									"successCriteria": {
										"type": "array",
										"description": "List of success criteria (structured objects)",
										"items": {
											"type": "object",
											"properties": {
												"type": {
													"type": "string",
													"description": "Success criterion type"
												},
												"params": {
													"type": "object",
													"description": "Success criterion parameters"
												}
											},
											"required": [
												"type",
												"params"
											]
										}
									},
									"maxTurns": {
										"type": "integer",
										"description": "Maximum number of turns"
									},
									"timeout": {
										"type": "integer",
										"description": "Timeout in seconds"
									},
									"aiAgentReferenceId": {
										"type": "string",
										"description": "Reference ID of the AI Agent"
									},
									"flowReferenceId": {
										"type": "string",
										"description": "Reference ID of the Flow"
									},
									"jobNodeId": {
										"type": "string",
										"description": "Job Node ID for precise tool context tracking"
									}
								},
								"required": [
									"projectReference",
									"name",
									"persona",
									"personaName",
									"mission",
									"successCriteria"
								]
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Scenario created successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"id": {
											"type": "string",
											"description": "Unique identifier for the scenario"
										},
										"referenceId": {
											"type": "string",
											"description": "Reference ID for the scenario"
										},
										"name": {
											"type": "string",
											"description": "Name of the scenario"
										},
										"persona": {
											"type": "string",
											"description": "Persona description"
										},
										"personaName": {
											"type": "string",
											"description": "Name of the persona"
										},
										"mission": {
											"type": "string",
											"description": "Mission description"
										},
										"successCriteria": {
											"type": "array",
											"description": "List of success criteria (structured objects)",
											"items": {
												"type": "object",
												"properties": {
													"type": {
														"type": "string",
														"description": "Success criterion type"
													},
													"params": {
														"type": "object",
														"description": "Success criterion parameters"
													}
												},
												"required": [
													"type",
													"params"
												]
											}
										},
										"maxTurns": {
											"type": "integer",
											"description": "Maximum number of turns"
										},
										"timeout": {
											"type": "integer",
											"description": "Timeout in seconds"
										},
										"aiAgentReferenceId": {
											"type": "string",
											"description": "Reference ID of the AI Agent"
										},
										"aiAgentId": {
											"type": "string",
											"description": "Database ID of the AI Agent"
										},
										"flowReferenceId": {
											"type": "string",
											"description": "Reference ID of the Flow"
										},
										"flowId": {
											"type": "string",
											"description": "Database ID of the Flow"
										},
										"jobNodeId": {
											"type": "string",
											"description": "Job Node ID"
										},
										"organisationReference": {
											"type": "string",
											"description": "Organization reference"
										},
										"projectReference": {
											"type": "string",
											"description": "Project reference"
										},
										"createdAt": {
											"type": "integer",
											"format": "int64",
											"description": "Creation timestamp"
										},
										"createdBy": {
											"type": "string",
											"description": "User who created the scenario"
										},
										"updatedAt": {
											"type": "integer",
											"format": "int64",
											"description": "Last update timestamp"
										},
										"updatedBy": {
											"type": "string",
											"description": "User who last updated the scenario"
										},
										"lastChanged": {
											"type": "integer",
											"format": "int64",
											"description": "Last change timestamp"
										},
										"lastChangedBy": {
											"type": "string",
											"description": "User who made the last change"
										}
									},
									"required": [
										"id",
										"referenceId",
										"name",
										"persona",
										"personaName",
										"mission",
										"successCriteria",
										"organisationReference",
										"projectReference",
										"createdAt",
										"createdBy",
										"lastChanged",
										"lastChangedBy"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/simulations/batches": {
			"get": {
				"operationId": "getAllSimulationBatches",
				"summary": "Get all simulations",
				"description": "Retrieve a paginated list of all simulations.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"name": "filter",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Filter criteria for searching simulations"
					},
					{
						"name": "limit",
						"in": "query",
						"required": false,
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20
						},
						"description": "Number of items to return per page"
					},
					{
						"name": "skip",
						"in": "query",
						"required": false,
						"schema": {
							"type": "integer",
							"minimum": 0,
							"default": 0
						},
						"description": "Number of items to skip"
					},
					{
						"name": "sort",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Sort order (e.g., 'name:asc', 'createdAt:desc')"
					},
					{
						"in": "query",
						"name": "next",
						"schema": {
							"type": "string"
						},
						"description": "Pagination cursor for next page"
					},
					{
						"in": "query",
						"name": "previous",
						"schema": {
							"type": "string"
						},
						"description": "Pagination cursor for previous page"
					},
					{
						"name": "status",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string",
							"enum": [
								"STOPPED",
								"IN_PROGRESS",
								"COMPLETED",
								"FAILED"
							]
						},
						"description": "Filter by simulation status"
					},
					{
						"name": "timespan",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Filter by time range (e.g., '7d', '30d', '1y')"
					},
					{
						"name": "timezone",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Timezone for timespan filtering (e.g., 'UTC', 'America/New_York')"
					},
					{
						"name": "endPointType",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Filter by endpoint type"
					},
					{
						"name": "scenariosIds",
						"in": "query",
						"required": false,
						"schema": {
							"type": "array",
							"items": {
								"type": "string"
							}
						},
						"style": "form",
						"explode": false,
						"description": "Filter by simulation references (comma-separated list of simulation IDs)"
					}
				],
				"responses": {
					"200": {
						"description": "List of simulations retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": {
											"type": "array",
											"items": {
												"type": "object",
												"properties": {
													"id": {
														"type": "string",
														"description": "Unique identifier for the simulation"
													},
													"referenceId": {
														"type": "string",
														"description": "Reference ID for the simulation"
													},
													"simulationReference": {
														"type": "string",
														"description": "Reference ID of the simulated scenario"
													},
													"status": {
														"type": "string",
														"enum": [
															"pending",
															"running",
															"completed",
															"failed",
															"stopped"
														],
														"description": "Current status of the simulation"
													},
													"runs": {
														"type": "integer",
														"description": "Number of runs in this simulation"
													},
													"completedRuns": {
														"type": "integer",
														"description": "Number of completed runs"
													},
													"failedRuns": {
														"type": "integer",
														"description": "Number of failed runs"
													},
													"createdAt": {
														"type": "integer",
														"format": "int64",
														"description": "Creation timestamp"
													},
													"startedAt": {
														"type": "integer",
														"format": "int64",
														"nullable": true,
														"description": "Start timestamp"
													},
													"completedAt": {
														"type": "integer",
														"format": "int64",
														"nullable": true,
														"description": "Completion timestamp"
													}
												},
												"required": [
													"id",
													"referenceId",
													"simulationReference",
													"status",
													"runs",
													"completedRuns",
													"failedRuns",
													"createdAt"
												]
											},
											"description": "Array of simulation objects"
										},
										"pagination": {
											"type": "object",
											"properties": {
												"limit": {
													"type": "integer",
													"description": "Number of items per page"
												},
												"skip": {
													"type": "integer",
													"description": "Number of items skipped"
												},
												"total": {
													"type": "integer",
													"description": "Total number of items"
												},
												"hasNext": {
													"type": "boolean",
													"description": "Whether there are more items"
												},
												"hasPrevious": {
													"type": "boolean",
													"description": "Whether there are previous items"
												},
												"next": {
													"type": "string",
													"nullable": true,
													"description": "Cursor for next page"
												},
												"previous": {
													"type": "string",
													"nullable": true,
													"description": "Cursor for previous page"
												}
											},
											"required": [
												"limit",
												"skip",
												"total",
												"hasNext",
												"hasPrevious"
											]
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/simulations/{simulationReference}": {
			"get": {
				"operationId": "getSimulationById",
				"summary": "Get scenario by ID",
				"description": "Retrieve a specific scenario by its reference ID.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the scenario"
					}
				],
				"responses": {
					"200": {
						"description": "Scenario retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"id": {
											"type": "string",
											"description": "Unique identifier for the scenario"
										},
										"referenceId": {
											"type": "string",
											"description": "Reference ID for the scenario"
										},
										"name": {
											"type": "string",
											"description": "Name of the scenario"
										},
										"persona": {
											"type": "string",
											"description": "Persona description"
										},
										"personaName": {
											"type": "string",
											"description": "Name of the persona"
										},
										"mission": {
											"type": "string",
											"description": "Mission description"
										},
										"successCriteria": {
											"type": "array",
											"description": "List of success criteria (structured objects)",
											"items": {
												"type": "object",
												"properties": {
													"type": {
														"type": "string",
														"description": "Success criterion type"
													},
													"params": {
														"type": "object",
														"description": "Success criterion parameters"
													}
												},
												"required": [
													"type",
													"params"
												]
											}
										},
										"maxTurns": {
											"type": "integer",
											"description": "Maximum number of turns"
										},
										"timeout": {
											"type": "integer",
											"description": "Timeout in seconds"
										},
										"aiAgentReferenceId": {
											"type": "string",
											"description": "Reference ID of the AI Agent"
										},
										"aiAgentId": {
											"type": "string",
											"description": "Database ID of the AI Agent"
										},
										"flowReferenceId": {
											"type": "string",
											"description": "Reference ID of the Flow"
										},
										"flowId": {
											"type": "string",
											"description": "Database ID of the Flow"
										},
										"jobNodeId": {
											"type": "string",
											"description": "Job Node ID"
										},
										"organisationReference": {
											"type": "string",
											"description": "Organization reference"
										},
										"projectReference": {
											"type": "string",
											"description": "Project reference"
										},
										"createdAt": {
											"type": "integer",
											"format": "int64",
											"description": "Creation timestamp"
										},
										"createdBy": {
											"type": "string",
											"description": "User who created the scenario"
										},
										"updatedAt": {
											"type": "integer",
											"format": "int64",
											"description": "Last update timestamp"
										},
										"updatedBy": {
											"type": "string",
											"description": "User who last updated the scenario"
										},
										"lastChanged": {
											"type": "integer",
											"format": "int64",
											"description": "Last change timestamp"
										},
										"lastChangedBy": {
											"type": "string",
											"description": "User who made the last change"
										}
									},
									"required": [
										"id",
										"referenceId",
										"name",
										"persona",
										"personaName",
										"mission",
										"successCriteria",
										"organisationReference",
										"projectReference",
										"createdAt",
										"createdBy",
										"lastChanged",
										"lastChangedBy"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"404": {
						"description": "Not Found - Resource not found",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Not found error message"
										},
										"code": {
											"type": "string",
											"description": "Not found error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			},
			"patch": {
				"operationId": "updateSimulation",
				"summary": "Update scenario",
				"description": "Update an existing scenario with new configuration.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the scenario"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"name": {
										"type": "string",
										"description": "Name of the scenario"
									},
									"persona": {
										"type": "string",
										"description": "Persona description"
									},
									"personaName": {
										"type": "string",
										"description": "Name of the persona"
									},
									"mission": {
										"type": "string",
										"description": "Mission description"
									},
									"successCriteria": {
										"type": "array",
										"description": "List of success criteria (structured objects)",
										"items": {
											"type": "object",
											"properties": {
												"type": {
													"type": "string",
													"description": "Success criterion type"
												},
												"params": {
													"type": "object",
													"description": "Success criterion parameters"
												}
											},
											"required": [
												"type",
												"params"
											]
										}
									},
									"maxTurns": {
										"type": "integer",
										"description": "Maximum number of turns"
									},
									"timeout": {
										"type": "integer",
										"description": "Timeout in seconds"
									},
									"aiAgentReferenceId": {
										"type": "string",
										"description": "Reference ID of the AI Agent"
									},
									"flowReferenceId": {
										"type": "string",
										"description": "Reference ID of the Flow"
									},
									"jobNodeId": {
										"type": "string",
										"description": "Job Node ID"
									}
								}
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Scenario updated successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"id": {
											"type": "string",
											"description": "Unique identifier for the scenario"
										},
										"referenceId": {
											"type": "string",
											"description": "Reference ID for the scenario"
										},
										"name": {
											"type": "string",
											"description": "Name of the scenario"
										},
										"persona": {
											"type": "string",
											"description": "Persona description"
										},
										"personaName": {
											"type": "string",
											"description": "Name of the persona"
										},
										"mission": {
											"type": "string",
											"description": "Mission description"
										},
										"successCriteria": {
											"type": "array",
											"description": "List of success criteria (structured objects)",
											"items": {
												"type": "object",
												"properties": {
													"type": {
														"type": "string",
														"description": "Success criterion type"
													},
													"params": {
														"type": "object",
														"description": "Success criterion parameters"
													}
												},
												"required": [
													"type",
													"params"
												]
											}
										},
										"maxTurns": {
											"type": "integer",
											"description": "Maximum number of turns"
										},
										"timeout": {
											"type": "integer",
											"description": "Timeout in seconds"
										},
										"aiAgentReferenceId": {
											"type": "string",
											"description": "Reference ID of the AI Agent"
										},
										"aiAgentId": {
											"type": "string",
											"description": "Database ID of the AI Agent"
										},
										"flowReferenceId": {
											"type": "string",
											"description": "Reference ID of the Flow"
										},
										"flowId": {
											"type": "string",
											"description": "Database ID of the Flow"
										},
										"jobNodeId": {
											"type": "string",
											"description": "Job Node ID"
										},
										"organisationReference": {
											"type": "string",
											"description": "Organization reference"
										},
										"projectReference": {
											"type": "string",
											"description": "Project reference"
										},
										"createdAt": {
											"type": "integer",
											"format": "int64",
											"description": "Creation timestamp"
										},
										"createdBy": {
											"type": "string",
											"description": "User who created the scenario"
										},
										"updatedAt": {
											"type": "integer",
											"format": "int64",
											"description": "Last update timestamp"
										},
										"updatedBy": {
											"type": "string",
											"description": "User who last updated the scenario"
										},
										"lastChanged": {
											"type": "integer",
											"format": "int64",
											"description": "Last change timestamp"
										},
										"lastChangedBy": {
											"type": "string",
											"description": "User who made the last change"
										}
									},
									"required": [
										"id",
										"referenceId",
										"name",
										"persona",
										"personaName",
										"mission",
										"successCriteria",
										"organisationReference",
										"projectReference",
										"createdAt",
										"createdBy",
										"lastChanged",
										"lastChangedBy"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"404": {
						"description": "Not Found - Resource not found",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Not found error message"
										},
										"code": {
											"type": "string",
											"description": "Not found error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			},
			"delete": {
				"operationId": "deleteSimulation",
				"summary": "Delete scenario",
				"description": "Delete a scenario and all its associated data.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the scenario"
					}
				],
				"responses": {
					"204": {
						"description": "Scenario deleted successfully"
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"404": {
						"description": "Not Found - Resource not found",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Not found error message"
										},
										"code": {
											"type": "string",
											"description": "Not found error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/simulations/{simulationReference}/schedule": {
			"post": {
				"operationId": "scheduleSimulation",
				"summary": "Run scenario",
				"description": "Run multiple executions of a scenario.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the scenario"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"projectReference": {
										"type": "string",
										"description": "Project reference (required in body)"
									},
									"name": {
										"type": "string",
										"description": "Name for this simulation"
									},
									"numberOfExecutions": {
										"type": "integer",
										"description": "Number of simulation runs to execute in this simulation",
										"minimum": 1
									},
									"endPointType": {
										"type": "string",
										"description": "Endpoint type for simulation execution (e.g., 'api', 'rpc')"
									},
									"runConfig": {
										"type": "object",
										"description": "Configuration for simulation execution",
										"properties": {
											"flowReferenceId": {
												"type": "string",
												"description": "Flow reference ID"
											},
											"localeReferenceId": {
												"type": "string",
												"description": "Locale reference ID (optional)"
											},
											"entrypoint": {
												"type": "string",
												"description": "Entry point for the flow"
											},
											"largeLanguageModelReferenceId": {
												"type": "string",
												"description": "LLM reference ID to use for this simulation"
											},
											"userId": {
												"type": "string",
												"description": "User ID (optional)"
											},
											"data": {
												"type": "object",
												"description": "Optional object containing arbitrary metadata",
												"additionalProperties": true
											},
											"enableMocking": {
												"type": "boolean",
												"description": "Enable mocking for this simulation run (optional)"
											}
										},
										"required": [
											"flowReferenceId",
											"entrypoint",
											"largeLanguageModelReferenceId"
										]
									}
								},
								"required": [
									"projectReference",
									"name",
									"numberOfExecutions",
									"runConfig"
								]
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Scenario execution started successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"id": {
											"type": "string",
											"description": "Unique identifier for the simulation"
										},
										"referenceId": {
											"type": "string",
											"description": "Reference ID for the simulation"
										},
										"simulationReference": {
											"type": "string",
											"description": "Reference ID of the simulated scenario"
										},
										"status": {
											"type": "string",
											"enum": [
												"pending",
												"running",
												"completed",
												"failed",
												"stopped"
											],
											"description": "Current status of the simulation"
										},
										"runs": {
											"type": "integer",
											"description": "Number of runs in this simulation"
										},
										"completedRuns": {
											"type": "integer",
											"description": "Number of completed runs"
										},
										"failedRuns": {
											"type": "integer",
											"description": "Number of failed runs"
										},
										"createdAt": {
											"type": "integer",
											"format": "int64",
											"description": "Creation timestamp"
										},
										"startedAt": {
											"type": "integer",
											"format": "int64",
											"nullable": true,
											"description": "Start timestamp"
										},
										"completedAt": {
											"type": "integer",
											"format": "int64",
											"nullable": true,
											"description": "Completion timestamp"
										}
									},
									"required": [
										"id",
										"referenceId",
										"simulationReference",
										"status",
										"runs",
										"completedRuns",
										"failedRuns",
										"createdAt"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"404": {
						"description": "Not Found - Resource not found",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Not found error message"
										},
										"code": {
											"type": "string",
											"description": "Not found error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/simulations/{simulationReference}/batches": {
			"get": {
				"operationId": "getSimulationBatchesBySimulation",
				"summary": "Get simulations by scenarios",
				"description": "Retrieve all simulations for a specific scenario.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the scenario"
					},
					{
						"name": "filter",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Filter criteria for searching simulations"
					},
					{
						"name": "limit",
						"in": "query",
						"required": false,
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20
						},
						"description": "Number of items to return per page"
					},
					{
						"name": "skip",
						"in": "query",
						"required": false,
						"schema": {
							"type": "integer",
							"minimum": 0,
							"default": 0
						},
						"description": "Number of items to skip"
					},
					{
						"name": "sort",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Sort order (e.g., 'name:asc', 'createdAt:desc')"
					},
					{
						"in": "query",
						"name": "next",
						"schema": {
							"type": "string"
						},
						"description": "Pagination cursor for next page"
					},
					{
						"in": "query",
						"name": "previous",
						"schema": {
							"type": "string"
						},
						"description": "Pagination cursor for previous page"
					},
					{
						"name": "status",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string",
							"enum": [
								"STOPPED",
								"IN_PROGRESS",
								"COMPLETED",
								"FAILED"
							]
						},
						"description": "Filter by simulation status"
					},
					{
						"name": "timespan",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Filter by time range (e.g., '7d', '30d', '1y')"
					},
					{
						"name": "timezone",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Timezone for timespan filtering (e.g., 'UTC', 'America/New_York')"
					},
					{
						"name": "endPointType",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Filter by endpoint type"
					}
				],
				"responses": {
					"200": {
						"description": "List of simulations retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": {
											"type": "array",
											"items": {
												"type": "object",
												"properties": {
													"id": {
														"type": "string",
														"description": "Unique identifier for the simulation."
													},
													"referenceId": {
														"type": "string",
														"description": "Reference ID for the simulation"
													},
													"simulationReference": {
														"type": "string",
														"description": "Reference ID of the simulated scenario"
													},
													"status": {
														"type": "string",
														"enum": [
															"pending",
															"running",
															"completed",
															"failed",
															"stopped"
														],
														"description": "Current status of the simulation"
													},
													"runs": {
														"type": "integer",
														"description": "Number of runs in this simulation"
													},
													"completedRuns": {
														"type": "integer",
														"description": "Number of completed runs"
													},
													"failedRuns": {
														"type": "integer",
														"description": "Number of failed runs"
													},
													"createdAt": {
														"type": "integer",
														"format": "int64",
														"description": "Creation timestamp"
													},
													"startedAt": {
														"type": "integer",
														"format": "int64",
														"nullable": true,
														"description": "Start timestamp"
													},
													"completedAt": {
														"type": "integer",
														"format": "int64",
														"nullable": true,
														"description": "Completion timestamp"
													}
												},
												"required": [
													"id",
													"referenceId",
													"simulationReference",
													"status",
													"runs",
													"completedRuns",
													"failedRuns",
													"createdAt"
												]
											},
											"description": "Array of simulations objects"
										},
										"pagination": {
											"type": "object",
											"properties": {
												"limit": {
													"type": "integer",
													"description": "Number of items per page"
												},
												"skip": {
													"type": "integer",
													"description": "Number of items skipped"
												},
												"total": {
													"type": "integer",
													"description": "Total number of items"
												},
												"hasNext": {
													"type": "boolean",
													"description": "Whether there are more items"
												},
												"hasPrevious": {
													"type": "boolean",
													"description": "Whether there are previous items"
												},
												"next": {
													"type": "string",
													"nullable": true,
													"description": "Cursor for next page"
												},
												"previous": {
													"type": "string",
													"nullable": true,
													"description": "Cursor for previous page"
												}
											},
											"required": [
												"limit",
												"skip",
												"total",
												"hasNext",
												"hasPrevious"
											]
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/simulations/{simulationReference}/batches/{simulationRunBatchReference}": {
			"get": {
				"operationId": "getSimulationBatchById",
				"summary": "Get simulation by ID",
				"description": "Retrieve a specific simulation by its reference ID.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the scenario"
					},
					{
						"in": "path",
						"name": "simulationRunBatchReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the simulation"
					}
				],
				"responses": {
					"200": {
						"description": "Simulation retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"id": {
											"type": "string",
											"description": "Unique identifier for the simulation"
										},
										"referenceId": {
											"type": "string",
											"description": "Reference ID for the simulation"
										},
										"simulationReference": {
											"type": "string",
											"description": "Reference ID of the simulated scenario"
										},
										"status": {
											"type": "string",
											"enum": [
												"pending",
												"running",
												"completed",
												"failed",
												"stopped"
											],
											"description": "Current status of the simulation"
										},
										"runs": {
											"type": "integer",
											"description": "Number of runs in this simulation"
										},
										"completedRuns": {
											"type": "integer",
											"description": "Number of completed runs"
										},
										"failedRuns": {
											"type": "integer",
											"description": "Number of failed runs"
										},
										"createdAt": {
											"type": "integer",
											"format": "int64",
											"description": "Creation timestamp"
										},
										"startedAt": {
											"type": "integer",
											"format": "int64",
											"nullable": true,
											"description": "Start timestamp"
										},
										"completedAt": {
											"type": "integer",
											"format": "int64",
											"nullable": true,
											"description": "Completion timestamp"
										}
									},
									"required": [
										"id",
										"referenceId",
										"simulationReference",
										"status",
										"runs",
										"completedRuns",
										"failedRuns",
										"createdAt"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"404": {
						"description": "Not Found - Simulation not found",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Not found error message",
											"example": "Simulation not found"
										},
										"code": {
											"type": "string",
											"description": "Not found error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			},
			"post": {
				"operationId": "stopSimulationBatch",
				"summary": "Stop simulation",
				"description": "Stop a running simulation and all its active runs.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the scenario"
					},
					{
						"in": "path",
						"name": "simulationRunBatchReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the simulation"
					}
				],
				"responses": {
					"200": {
						"description": "Simulation stop signal sent successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"message": {
											"type": "string",
											"description": "Success message",
											"example": "Simulation stop signal sent successfully."
										},
										"simulationRunBatchId": {
											"type": "string",
											"description": "Reference ID of the simulation that was signaled to stop"
										}
									},
									"required": [
										"message",
										"simulationRunBatchId"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/simulations/{simulationReference}/batches/{simulationRunBatchReference}/runs": {
			"get": {
				"operationId": "getSimulationRunsByBatch",
				"summary": "Get simulation runs by simulation",
				"description": "Retrieve all simulation runs for a specific simulation.",
				"tags": [
					"Simulation Runs"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the scenario"
					},
					{
						"in": "path",
						"name": "simulationRunBatchReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the simulation"
					},
					{
						"name": "filter",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Filter criteria for searching simulations"
					},
					{
						"name": "limit",
						"in": "query",
						"required": false,
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20
						},
						"description": "Number of items to return per page"
					},
					{
						"name": "skip",
						"in": "query",
						"required": false,
						"schema": {
							"type": "integer",
							"minimum": 0,
							"default": 0
						},
						"description": "Number of items to skip"
					},
					{
						"name": "sort",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Sort order (e.g., 'name:asc', 'createdAt:desc')"
					},
					{
						"in": "query",
						"name": "next",
						"schema": {
							"type": "string"
						},
						"description": "Pagination cursor for next page"
					},
					{
						"in": "query",
						"name": "previous",
						"schema": {
							"type": "string"
						},
						"description": "Pagination cursor for previous page"
					},
					{
						"in": "query",
						"name": "endPointType",
						"schema": {
							"type": "string"
						},
						"description": "Filter by endpoint type"
					}
				],
				"responses": {
					"200": {
						"description": "List of simulation runs retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": {
											"type": "array",
											"description": "Array of simulation run objects",
											"items": {
												"type": "object",
												"properties": {
													"id": {
														"type": "string",
														"description": "Unique identifier for the simulation run"
													},
													"organisationReference": {
														"type": "string",
														"description": "Organization reference"
													},
													"projectReference": {
														"type": "string",
														"description": "Project reference"
													},
													"simulationReference": {
														"type": "string",
														"description": "Reference ID of the simulated scenario"
													},
													"simulationRunBatchReference": {
														"type": "string",
														"description": "Reference ID of the simulation"
													},
													"sequence": {
														"type": "integer",
														"description": "Sequence number of this run in the simulation"
													},
													"largeLanguageModelReferenceId": {
														"type": "string",
														"description": "LLM reference ID used for this run"
													},
													"endPointType": {
														"type": "string",
														"description": "Endpoint type used for execution"
													},
													"turns": {
														"type": "array",
														"description": "Array of conversation turns",
														"items": {
															"type": "object",
															"properties": {
																"id": {
																	"type": "string",
																	"description": "Turn identifier"
																},
																"sequence": {
																	"type": "integer",
																	"description": "Turn sequence number"
																},
																"text": {
																	"type": "string",
																	"description": "Turn text content"
																},
																"data": {
																	"type": "object",
																	"description": "Turn metadata and additional data"
																},
																"createdAt": {
																	"type": "integer",
																	"format": "int64",
																	"description": "Turn creation timestamp"
																}
															}
														}
													},
													"totalTurns": {
														"type": "integer",
														"description": "Total number of turns in this run"
													},
													"maxTurns": {
														"type": "integer",
														"description": "Maximum allowed turns"
													},
													"successCriteria": {
														"type": "array",
														"description": "Success criteria for this run",
														"items": {
															"type": "object",
															"properties": {
																"type": {
																	"type": "string",
																	"description": "Success criterion type"
																},
																"params": {
																	"type": "object",
																	"description": "Success criterion parameters"
																}
															},
															"required": [
																"type",
																"params"
															]
														}
													},
													"metrics": {
														"type": "object",
														"description": "Metrics and results of the simulation run",
														"properties": {
															"sentiment": {
																"type": "string",
																"enum": [
																	"positive",
																	"negative",
																	"neutral"
																],
																"description": "Sentiment analysis result"
															},
															"success": {
																"type": "boolean",
																"description": "Whether the run was successful"
															},
															"results": {
																"type": "array",
																"description": "Success criteria evaluation results",
																"items": {
																	"type": "object"
																}
															},
															"successRate": {
																"type": "object",
																"description": "Success rate calculation",
																"properties": {
																	"percentage": {
																		"type": "number",
																		"format": "float"
																	},
																	"numerator": {
																		"type": "integer"
																	},
																	"denominator": {
																		"type": "integer"
																	}
																}
															},
															"summary": {
																"type": "string",
																"description": "Summary of the simulation run"
															},
															"isBatchStopped": {
																"type": "boolean",
																"description": "Whether the simulation was stopped"
															},
															"landedAfterStop": {
																"type": "boolean",
																"description": "True when this run is NOT part of the evaluated batch/variant result: the stop condition was met on an earlier set of runs (by sequence/variantSequence) and this run only executed because it was already dispatched. Excludes the run that carried isBatchStopped and runs within the result cutoff."
															},
															"isConversationEnded": {
																"type": "boolean",
																"description": "Whether the conversation ended naturally"
															},
															"errorInfo": {
																"type": "object",
																"description": "Error information if run failed",
																"properties": {
																	"category": {
																		"type": "string",
																		"enum": [
																			"NONE",
																			"LLM_PROVIDER_ERROR",
																			"AI_AGENT_TIMEOUT",
																			"AI_AGENT_ERROR",
																			"UNKNOWN"
																		],
																		"description": "Error category"
																	},
																	"message": {
																		"type": "string",
																		"description": "User-friendly error message"
																	},
																	"technicalDetails": {
																		"type": "string",
																		"description": "Technical error details"
																	}
																}
															},
															"status": {
																"type": "string",
																"enum": [
																	"SUCCESS",
																	"FAILED",
																	"ERROR"
																],
																"description": "Overall status of the run"
															}
														}
													},
													"createdAt": {
														"type": "integer",
														"format": "int64",
														"description": "Creation timestamp"
													},
													"createdBy": {
														"type": "string",
														"description": "User who created this run"
													},
													"duration": {
														"type": "integer",
														"description": "Duration of the run in milliseconds"
													},
													"expiresAt": {
														"type": "string",
														"format": "date-time",
														"description": "Expiration timestamp"
													}
												},
												"required": [
													"id",
													"organisationReference",
													"projectReference",
													"simulationReference",
													"simulationRunBatchReference",
													"sequence",
													"largeLanguageModelReferenceId",
													"turns",
													"totalTurns",
													"successCriteria",
													"metrics",
													"createdAt",
													"createdBy"
												]
											}
										},
										"pagination": {
											"type": "object",
											"properties": {
												"limit": {
													"type": "integer",
													"description": "Number of items per page"
												},
												"skip": {
													"type": "integer",
													"description": "Number of items skipped"
												},
												"total": {
													"type": "integer",
													"description": "Total number of items"
												},
												"hasNext": {
													"type": "boolean",
													"description": "Whether there are more items"
												},
												"hasPrevious": {
													"type": "boolean",
													"description": "Whether there are previous items"
												},
												"next": {
													"type": "string",
													"nullable": true,
													"description": "Cursor for next page"
												},
												"previous": {
													"type": "string",
													"nullable": true,
													"description": "Cursor for previous page"
												}
											},
											"required": [
												"limit",
												"skip",
												"total",
												"hasNext",
												"hasPrevious"
											]
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/simulations/{simulationReference}/batches/{simulationRunBatchReference}/runs/{simulationRunReference}": {
			"get": {
				"operationId": "getSimulationRunById",
				"summary": "Get simulation run by ID",
				"description": "Retrieve a specific simulation run by its reference ID.",
				"tags": [
					"Simulation Runs"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the scenario"
					},
					{
						"in": "path",
						"name": "simulationRunBatchReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the simulation"
					},
					{
						"in": "path",
						"name": "simulationRunReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the simulation run"
					}
				],
				"responses": {
					"200": {
						"description": "Simulation run retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"id": {
											"type": "string",
											"description": "Unique identifier for the simulation run"
										},
										"organisationReference": {
											"type": "string",
											"description": "Organization reference"
										},
										"projectReference": {
											"type": "string",
											"description": "Project reference"
										},
										"simulationReference": {
											"type": "string",
											"description": "Reference ID of the simulated scenario"
										},
										"simulationRunBatchReference": {
											"type": "string",
											"description": "Reference ID of the simulation"
										},
										"sequence": {
											"type": "integer",
											"description": "Sequence number of this run in the simulation"
										},
										"largeLanguageModelReferenceId": {
											"type": "string",
											"description": "LLM reference ID used for this run"
										},
										"endPointType": {
											"type": "string",
											"description": "Endpoint type used for execution"
										},
										"turns": {
											"type": "array",
											"description": "Array of conversation turns",
											"items": {
												"type": "object",
												"properties": {
													"id": {
														"type": "string",
														"description": "Turn identifier"
													},
													"sequence": {
														"type": "integer",
														"description": "Turn sequence number"
													},
													"text": {
														"type": "string",
														"description": "Turn text content"
													},
													"data": {
														"type": "object",
														"description": "Turn metadata and additional data"
													},
													"createdAt": {
														"type": "integer",
														"format": "int64",
														"description": "Turn creation timestamp"
													}
												}
											}
										},
										"totalTurns": {
											"type": "integer",
											"description": "Total number of turns in this run"
										},
										"maxTurns": {
											"type": "integer",
											"description": "Maximum allowed turns"
										},
										"successCriteria": {
											"type": "array",
											"description": "Success criteria for this run",
											"items": {
												"type": "object",
												"properties": {
													"type": {
														"type": "string",
														"description": "Success criterion type"
													},
													"params": {
														"type": "object",
														"description": "Success criterion parameters"
													}
												},
												"required": [
													"type",
													"params"
												]
											}
										},
										"metrics": {
											"type": "object",
											"description": "Metrics and results of the simulation run",
											"properties": {
												"sentiment": {
													"type": "string",
													"enum": [
														"positive",
														"negative",
														"neutral"
													],
													"description": "Sentiment analysis result"
												},
												"success": {
													"type": "boolean",
													"description": "Whether the run was successful"
												},
												"results": {
													"type": "array",
													"description": "Success criteria evaluation results",
													"items": {
														"type": "object"
													}
												},
												"successRate": {
													"type": "object",
													"description": "Success rate calculation",
													"properties": {
														"percentage": {
															"type": "number",
															"format": "float"
														},
														"numerator": {
															"type": "integer"
														},
														"denominator": {
															"type": "integer"
														}
													}
												},
												"summary": {
													"type": "string",
													"description": "Summary of the simulation run"
												},
												"isBatchStopped": {
													"type": "boolean",
													"description": "Whether the simulation was stopped"
												},
												"landedAfterStop": {
													"type": "boolean",
													"description": "True when this run is NOT part of the evaluated batch/variant result: the stop condition was met on an earlier set of runs (by sequence/variantSequence) and this run only executed because it was already dispatched. Excludes the run that carried isBatchStopped and runs within the result cutoff."
												},
												"isConversationEnded": {
													"type": "boolean",
													"description": "Whether the conversation ended naturally"
												},
												"errorInfo": {
													"type": "object",
													"description": "Error information if run failed",
													"properties": {
														"category": {
															"type": "string",
															"enum": [
																"NONE",
																"LLM_PROVIDER_ERROR",
																"AI_AGENT_TIMEOUT",
																"AI_AGENT_ERROR",
																"UNKNOWN"
															],
															"description": "Error category"
														},
														"message": {
															"type": "string",
															"description": "User-friendly error message"
														},
														"technicalDetails": {
															"type": "string",
															"description": "Technical error details"
														}
													}
												},
												"status": {
													"type": "string",
													"enum": [
														"SUCCESS",
														"FAILED",
														"ERROR"
													],
													"description": "Overall status of the run"
												}
											},
											"required": [
												"sentiment",
												"success"
											]
										},
										"createdAt": {
											"type": "integer",
											"format": "int64",
											"description": "Creation timestamp"
										},
										"createdBy": {
											"type": "string",
											"description": "User who created this run"
										},
										"duration": {
											"type": "integer",
											"description": "Duration of the run in milliseconds"
										},
										"expiresAt": {
											"type": "string",
											"format": "date-time",
											"description": "Expiration timestamp"
										}
									},
									"required": [
										"id",
										"organisationReference",
										"projectReference",
										"simulationReference",
										"simulationRunBatchReference",
										"sequence",
										"largeLanguageModelReferenceId",
										"turns",
										"totalTurns",
										"successCriteria",
										"metrics",
										"createdAt",
										"createdBy"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"404": {
						"description": "Not Found - Simulation run not found",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Not found error message"
										},
										"code": {
											"type": "string",
											"description": "Not found error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/simulations/{simulationReference}/clone": {
			"post": {
				"operationId": "cloneSimulation",
				"summary": "Clone scenario",
				"description": "Clone a scenario and optionally provide a new name for the cloned scenario.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the scenario to clone"
					}
				],
				"requestBody": {
					"required": false,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"name": {
										"type": "string",
										"description": "Optional new name for the cloned scenario"
									}
								}
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Scenario cloned successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"id": {
											"type": "string",
											"description": "Unique identifier for the scenario"
										},
										"referenceId": {
											"type": "string",
											"description": "Reference ID for the scenario"
										},
										"name": {
											"type": "string",
											"description": "Name of the scenario"
										},
										"persona": {
											"type": "string",
											"description": "Persona description"
										},
										"personaName": {
											"type": "string",
											"description": "Name of the persona"
										},
										"mission": {
											"type": "string",
											"description": "Mission description"
										},
										"successCriteria": {
											"type": "array",
											"description": "List of success criteria (structured objects)",
											"items": {
												"type": "object",
												"properties": {
													"type": {
														"type": "string",
														"description": "Success criterion type"
													},
													"params": {
														"type": "object",
														"description": "Success criterion parameters"
													}
												},
												"required": [
													"type",
													"params"
												]
											}
										},
										"maxTurns": {
											"type": "integer",
											"description": "Maximum number of turns"
										},
										"timeout": {
											"type": "integer",
											"description": "Timeout in seconds"
										},
										"aiAgentReferenceId": {
											"type": "string",
											"description": "Reference ID of the AI Agent"
										},
										"aiAgentId": {
											"type": "string",
											"description": "Database ID of the AI Agent"
										},
										"flowReferenceId": {
											"type": "string",
											"description": "Reference ID of the Flow"
										},
										"flowId": {
											"type": "string",
											"description": "Database ID of the Flow"
										},
										"jobNodeId": {
											"type": "string",
											"description": "Job Node ID"
										},
										"organisationReference": {
											"type": "string",
											"description": "Organization reference"
										},
										"projectReference": {
											"type": "string",
											"description": "Project reference"
										},
										"createdAt": {
											"type": "integer",
											"format": "int64",
											"description": "Creation timestamp"
										},
										"createdBy": {
											"type": "string",
											"description": "User who created the scenario"
										},
										"updatedAt": {
											"type": "integer",
											"format": "int64",
											"description": "Last update timestamp"
										},
										"updatedBy": {
											"type": "string",
											"description": "User who last updated the scenario"
										},
										"lastChanged": {
											"type": "integer",
											"format": "int64",
											"description": "Last change timestamp"
										},
										"lastChangedBy": {
											"type": "string",
											"description": "User who made the last change"
										}
									},
									"required": [
										"id",
										"referenceId",
										"name",
										"persona",
										"personaName",
										"mission",
										"successCriteria",
										"organisationReference",
										"projectReference",
										"createdAt",
										"createdBy",
										"lastChanged",
										"lastChangedBy"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"404": {
						"description": "Not Found - Resource not found",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Not found error message"
										},
										"code": {
											"type": "string",
											"description": "Not found error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/simulations/{simulationReference}/schedules": {
			"get": {
				"operationId": "getSchedulersBySimulation",
				"summary": "Get scheduler configuration for a simulation",
				"description": "Retrieve the scheduler configuration associated with a specific simulation.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the simulation"
					}
				],
				"responses": {
					"200": {
						"description": "Scheduler retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"scheduler": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string"
												},
												"simulationReference": {
													"type": "string"
												},
												"projectReference": {
													"type": "string"
												},
												"organisationReference": {
													"type": "string"
												},
												"runConfig": {
													"type": "object",
													"properties": {
														"flowReferenceId": {
															"type": "string"
														},
														"localeReferenceId": {
															"type": "string"
														},
														"entrypoint": {
															"type": "string"
														},
														"largeLanguageModelReferenceId": {
															"type": "string"
														},
														"userId": {
															"type": "string"
														},
														"finalPing": {
															"type": "number"
														},
														"data": {
															"type": "object",
															"additionalProperties": true
														},
														"enableMocking": {
															"type": "boolean"
														}
													}
												},
												"enableSchedule": {
													"type": "boolean"
												},
												"frequency": {
													"type": "string",
													"enum": [
														"daily",
														"every three days",
														"weekly",
														"biweekly",
														"monthly"
													]
												},
												"time": {
													"type": "string",
													"format": "date-time"
												},
												"numberOfRuns": {
													"type": "integer"
												},
												"nextScheduledRun": {
													"type": "string",
													"format": "date-time"
												},
												"emailNotifications": {
													"type": "array",
													"items": {
														"type": "string"
													}
												},
												"scenarioName": {
													"type": "string"
												},
												"runName": {
													"type": "string"
												},
												"endDate": {
													"type": "string",
													"format": "date-time"
												},
												"createdAt": {
													"type": "integer",
													"format": "int64"
												},
												"lastChanged": {
													"type": "integer",
													"format": "int64"
												},
												"createdBy": {
													"type": "string"
												},
												"lastChangedBy": {
													"type": "string"
												},
												"cronScheduler": {
													"type": "string"
												},
												"timezone": {
													"type": "string",
													"description": "IANA timezone used for scheduler recurrence calculations. Derived by the server from the project timezone settings and persisted on the scheduler. Not set directly in scheduler create/update requests.",
													"example": "Europe/Berlin"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"field": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"404": {
						"description": "Not Found - Resource not found",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			},
			"post": {
				"operationId": "createScheduler",
				"summary": "Create a scheduler for a simulation",
				"description": "Create a scheduler associated with a scenario to run simulations automatically.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the simulation"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"projectReference": {
										"type": "string",
										"description": "Project reference (required in body)"
									},
									"runConfig": {
										"type": "object",
										"properties": {
											"flowReferenceId": {
												"type": "string"
											},
											"localeReferenceId": {
												"type": "string"
											},
											"entrypoint": {
												"type": "string"
											},
											"largeLanguageModelReferenceId": {
												"type": "string"
											},
											"userId": {
												"type": "string"
											},
											"finalPing": {
												"type": "number"
											},
											"data": {
												"type": "object",
												"additionalProperties": true
											},
											"enableMocking": {
												"type": "boolean"
											}
										},
										"required": [
											"flowReferenceId",
											"entrypoint",
											"largeLanguageModelReferenceId"
										]
									},
									"enableSchedule": {
										"type": "boolean"
									},
									"frequency": {
										"type": "string",
										"enum": [
											"daily",
											"every three days",
											"weekly",
											"biweekly",
											"monthly"
										]
									},
									"time": {
										"type": "string",
										"format": "date-time"
									},
									"numberOfRuns": {
										"type": "integer"
									},
									"nextScheduledRun": {
										"type": "string",
										"format": "date-time"
									},
									"emailNotifications": {
										"type": "array",
										"items": {
											"type": "string"
										}
									},
									"scenarioName": {
										"type": "string"
									},
									"runName": {
										"type": "string"
									},
									"endDate": {
										"type": "string",
										"format": "date-time"
									}
								},
								"required": [
									"projectReference",
									"runConfig",
									"frequency",
									"time",
									"runName"
								],
								"description": "Note: timezone is server-derived from project settings."
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Scheduler created successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"scheduler": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string"
												},
												"simulationReference": {
													"type": "string"
												},
												"projectReference": {
													"type": "string"
												},
												"organisationReference": {
													"type": "string"
												},
												"runConfig": {
													"type": "object",
													"properties": {
														"flowReferenceId": {
															"type": "string"
														},
														"localeReferenceId": {
															"type": "string"
														},
														"entrypoint": {
															"type": "string"
														},
														"largeLanguageModelReferenceId": {
															"type": "string"
														},
														"userId": {
															"type": "string"
														},
														"finalPing": {
															"type": "number"
														},
														"data": {
															"type": "object",
															"additionalProperties": true
														},
														"enableMocking": {
															"type": "boolean"
														}
													}
												},
												"enableSchedule": {
													"type": "boolean"
												},
												"frequency": {
													"type": "string",
													"enum": [
														"daily",
														"every three days",
														"weekly",
														"biweekly",
														"monthly"
													]
												},
												"time": {
													"type": "string",
													"format": "date-time"
												},
												"numberOfRuns": {
													"type": "integer"
												},
												"nextScheduledRun": {
													"type": "string",
													"format": "date-time"
												},
												"emailNotifications": {
													"type": "array",
													"items": {
														"type": "string"
													}
												},
												"scenarioName": {
													"type": "string"
												},
												"runName": {
													"type": "string"
												},
												"endDate": {
													"type": "string",
													"format": "date-time"
												},
												"createdAt": {
													"type": "integer",
													"format": "int64"
												},
												"lastChanged": {
													"type": "integer",
													"format": "int64"
												},
												"createdBy": {
													"type": "string"
												},
												"lastChangedBy": {
													"type": "string"
												},
												"cronScheduler": {
													"type": "string"
												},
												"timezone": {
													"type": "string",
													"description": "IANA timezone used for scheduler recurrence calculations. Derived by the server from the project timezone settings and persisted on the scheduler. Not set directly in scheduler create/update requests.",
													"example": "Europe/Berlin"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"field": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/simulations/{simulationReference}/schedules/{schedulerReference}": {
			"patch": {
				"operationId": "updateScheduler",
				"summary": "Update a scheduler by reference",
				"description": "Update fields of an existing scheduler configuration by its reference.",
				"tags": [
					"Simulations"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"in": "path",
						"name": "simulationReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the simulation (unused for update but part of path)"
					},
					{
						"in": "path",
						"name": "schedulerReference",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Reference ID of the scheduler to update"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"description": "Any subset of fields to update",
								"properties": {
									"runConfig": {
										"type": "object",
										"properties": {
											"flowReferenceId": {
												"type": "string"
											},
											"localeReferenceId": {
												"type": "string"
											},
											"entrypoint": {
												"type": "string"
											},
											"largeLanguageModelReferenceId": {
												"type": "string"
											},
											"userId": {
												"type": "string"
											},
											"finalPing": {
												"type": "number"
											},
											"data": {
												"type": "object",
												"additionalProperties": true
											},
											"enableMocking": {
												"type": "boolean"
											}
										}
									},
									"enableSchedule": {
										"type": "boolean"
									},
									"frequency": {
										"type": "string",
										"enum": [
											"daily",
											"every three days",
											"weekly",
											"biweekly",
											"monthly"
										]
									},
									"time": {
										"type": "string",
										"format": "date-time"
									},
									"numberOfRuns": {
										"type": "integer"
									},
									"nextScheduledRun": {
										"type": "string",
										"format": "date-time"
									},
									"emailNotifications": {
										"type": "array",
										"items": {
											"type": "string"
										}
									},
									"scenarioName": {
										"type": "string"
									},
									"runName": {
										"type": "string"
									},
									"simulationReference": {
										"type": "string"
									},
									"endDate": {
										"type": "string",
										"format": "date-time"
									}
								}
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Scheduler updated successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"scheduler": {
											"type": "object",
											"properties": {
												"id": {
													"type": "string"
												},
												"simulationReference": {
													"type": "string"
												},
												"projectReference": {
													"type": "string"
												},
												"organisationReference": {
													"type": "string"
												},
												"runConfig": {
													"type": "object",
													"properties": {
														"flowReferenceId": {
															"type": "string"
														},
														"localeReferenceId": {
															"type": "string"
														},
														"entrypoint": {
															"type": "string"
														},
														"largeLanguageModelReferenceId": {
															"type": "string"
														},
														"userId": {
															"type": "string"
														},
														"finalPing": {
															"type": "number"
														},
														"data": {
															"type": "object",
															"additionalProperties": true
														},
														"enableMocking": {
															"type": "boolean"
														}
													}
												},
												"enableSchedule": {
													"type": "boolean"
												},
												"frequency": {
													"type": "string",
													"enum": [
														"daily",
														"every three days",
														"weekly",
														"biweekly",
														"monthly"
													]
												},
												"time": {
													"type": "string",
													"format": "date-time"
												},
												"numberOfRuns": {
													"type": "integer"
												},
												"nextScheduledRun": {
													"type": "string",
													"format": "date-time"
												},
												"emailNotifications": {
													"type": "array",
													"items": {
														"type": "string"
													}
												},
												"scenarioName": {
													"type": "string"
												},
												"runName": {
													"type": "string"
												},
												"endDate": {
													"type": "string",
													"format": "date-time"
												},
												"createdAt": {
													"type": "integer",
													"format": "int64"
												},
												"lastChanged": {
													"type": "integer",
													"format": "int64"
												},
												"createdBy": {
													"type": "string"
												},
												"lastChangedBy": {
													"type": "string"
												},
												"cronScheduler": {
													"type": "string"
												},
												"timezone": {
													"type": "string",
													"description": "IANA timezone used for scheduler recurrence calculations. Derived by the server from the project timezone settings and persisted on the scheduler. Not set directly in scheduler create/update requests.",
													"example": "Europe/Berlin"
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"field": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"404": {
						"description": "Not Found - Resource not found",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										},
										"code": {
											"type": "string"
										},
										"traceId": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/personas/options": {
			"post": {
				"operationId": "getPersonaOptions",
				"summary": "Get persona options (mission types and persona types)",
				"description": "Smart endpoint that handles multiple scenarios for getting persona options:\n- **Legacy**: Provide only `flowId` to analyze the entire flow\n- **AI Agent Specific**: Provide `flowId` + `aiagentReferenceId` to analyze a specific AI agent\n- **Job Node Specific**: Provide `flowId` + `aiagentReferenceId` + `jobNodeId` to analyze a specific job node\n",
				"tags": [
					"Personas"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"flowId": {
										"type": "string",
										"description": "Flow identifier (required for all scenarios)"
									},
									"aiagentReferenceId": {
										"type": "string",
										"description": "AI Agent reference ID (optional - for AI agent specific analysis)"
									},
									"jobNodeId": {
										"type": "string",
										"description": "Job Node ID (optional - requires aiagentReferenceId, for job node specific analysis)"
									}
								},
								"required": [
									"flowId"
								]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Persona options retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"simulationName": {
											"type": "string",
											"description": "Suggested name for the scenario based on the flow/agent context"
										},
										"missionTypes": {
											"type": "array",
											"description": "Available mission types with success criteria",
											"items": {
												"type": "object",
												"properties": {
													"name": {
														"type": "string",
														"description": "Name of the mission type"
													},
													"description": {
														"type": "string",
														"description": "Description of the mission"
													},
													"successCriteria": {
														"type": "array",
														"description": "Success criteria for this mission",
														"items": {
															"type": "object",
															"properties": {
																"name": {
																	"type": "string",
																	"description": "Name of the success criterion"
																},
																"description": {
																	"type": "string",
																	"description": "Description of the success criterion"
																}
															},
															"required": [
																"name",
																"description"
															]
														}
													}
												},
												"required": [
													"name",
													"description",
													"successCriteria"
												]
											}
										},
										"personaTypes": {
											"type": "array",
											"description": "Available persona types with behavioral characteristics",
											"items": {
												"type": "object",
												"properties": {
													"name": {
														"type": "string",
														"description": "Name of the persona type"
													},
													"description": {
														"type": "string",
														"description": "Description and behavioral characteristics of the persona"
													}
												},
												"required": [
													"name",
													"description"
												]
											}
										}
									},
									"required": [
										"simulationName",
										"missionTypes",
										"personaTypes"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/personas/generate": {
			"post": {
				"operationId": "generatePersonaPackages",
				"summary": "Generate persona packages",
				"description": "Generate persona packages based on selected mission type and persona type with auto-discovery of AI agents and tools from the flow.\nThis endpoint creates complete persona packages including scenario names, persona descriptions, missions, and success criteria.\n",
				"tags": [
					"Personas"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier (alternative to projectReference in body)"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"projectReference": {
										"type": "string",
										"description": "Project reference for context identification (alternative to projectId query parameter)"
									},
									"flowReferenceId": {
										"type": "string",
										"description": "Flow reference ID for AI agent and tool discovery"
									},
									"jobNodeId": {
										"type": "string",
										"description": "Optional: Target specific job node for precise tool discovery"
									},
									"selectedMissionType": {
										"type": "object",
										"description": "Selected mission type with success criteria",
										"properties": {
											"name": {
												"type": "string",
												"description": "Mission type name"
											},
											"description": {
												"type": "string",
												"description": "Mission type description"
											},
											"successCriteria": {
												"type": "array",
												"description": "Success criteria for this mission type",
												"items": {
													"type": "object",
													"properties": {
														"name": {
															"type": "string",
															"description": "Success criterion name"
														},
														"description": {
															"type": "string",
															"description": "Success criterion description"
														}
													},
													"required": [
														"name",
														"description"
													]
												}
											}
										},
										"required": [
											"name",
											"description",
											"successCriteria"
										]
									},
									"selectedPersonaType": {
										"type": "object",
										"description": "Selected persona type with characteristics",
										"properties": {
											"name": {
												"type": "string",
												"description": "Persona type name"
											},
											"description": {
												"type": "string",
												"description": "Persona type description and characteristics"
											}
										},
										"required": [
											"name",
											"description"
										]
									},
									"numberOfSuccessCriteria": {
										"type": "integer",
										"description": "Number of success criteria to generate per persona package",
										"minimum": 1
									},
									"requestedPackages": {
										"type": "integer",
										"description": "Number of persona packages to generate",
										"minimum": 1
									}
								},
								"required": [
									"flowReferenceId",
									"selectedMissionType",
									"selectedPersonaType",
									"numberOfSuccessCriteria",
									"requestedPackages"
								]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Persona packages generated successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"description": "Whether the generation was successful"
										},
										"personaPackages": {
											"type": "array",
											"description": "Array of generated persona packages",
											"items": {
												"type": "object",
												"properties": {
													"simulationName": {
														"type": "string",
														"description": "Generated scenario name"
													},
													"personaName": {
														"type": "string",
														"description": "Generated persona name"
													},
													"personaDescription": {
														"type": "string",
														"description": "Generated persona description"
													},
													"mission": {
														"type": "string",
														"description": "Generated mission"
													},
													"successCriteria": {
														"type": "array",
														"description": "Generated success criteria",
														"items": {
															"type": "object",
															"properties": {
																"type": {
																	"type": "string",
																	"description": "Success criterion type"
																},
																"params": {
																	"type": "object",
																	"description": "Success criterion parameters"
																}
															},
															"required": [
																"type",
																"params"
															]
														}
													}
												},
												"required": [
													"simulationName",
													"personaName",
													"personaDescription",
													"mission",
													"successCriteria"
												]
											}
										},
										"metadata": {
											"type": "object",
											"description": "Optional metadata about the generation",
											"properties": {
												"requestId": {
													"type": "string",
													"description": "Request identifier"
												},
												"processedAt": {
													"type": "string",
													"description": "Timestamp when processed"
												},
												"model": {
													"type": "string",
													"description": "LLM model used"
												}
											}
										}
									},
									"required": [
										"success",
										"personaPackages"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/personas/regenerate-field": {
			"post": {
				"operationId": "regeneratePersonaField",
				"summary": "Regenerate a specific field of a persona package",
				"description": "Regenerate a specific field of a persona package using LLM. Requires the full persona package context to regenerate any individual field.\nValid fields to regenerate: simulationName, personaName, personaDescription, mission, successCriteria\n",
				"tags": [
					"Personas"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"projectReference": {
										"type": "string",
										"description": "Project reference for context identification (alternative to projectId query parameter)"
									},
									"fieldToRegenerate": {
										"type": "string",
										"enum": [
											"simulationName",
											"personaName",
											"personaDescription",
											"mission",
											"successCriteria"
										],
										"description": "Field name to regenerate"
									},
									"simulationName": {
										"type": "string",
										"description": "Current scenario name"
									},
									"personaName": {
										"type": "string",
										"description": "Current persona name"
									},
									"personaDescription": {
										"type": "string",
										"description": "Current persona description"
									},
									"mission": {
										"type": "string",
										"description": "Current mission"
									},
									"successCriteria": {
										"type": "array",
										"description": "Current success criteria array",
										"items": {
											"type": "object",
											"properties": {
												"type": {
													"type": "string",
													"description": "Success criterion type"
												},
												"params": {
													"type": "object",
													"description": "Success criterion parameters"
												}
											},
											"required": [
												"type",
												"params"
											]
										}
									},
									"successCriteriaIndex": {
										"type": "integer",
										"description": "Optional: Index of specific success criterion to regenerate (only when fieldToRegenerate is 'successCriteria')"
									}
								},
								"required": [
									"fieldToRegenerate",
									"simulationName",
									"personaName",
									"personaDescription",
									"mission",
									"successCriteria"
								]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Persona field regenerated successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"description": "Whether the regeneration was successful"
										},
										"personaPackage": {
											"type": "object",
											"description": "Complete persona package with the regenerated field",
											"properties": {
												"simulationName": {
													"type": "string",
													"description": "Simulation name"
												},
												"personaName": {
													"type": "string",
													"description": "Persona name"
												},
												"personaDescription": {
													"type": "string",
													"description": "Persona description"
												},
												"mission": {
													"type": "string",
													"description": "Mission"
												},
												"successCriteria": {
													"type": "array",
													"description": "Success criteria",
													"items": {
														"type": "object",
														"properties": {
															"type": {
																"type": "string",
																"description": "Success criterion type"
															},
															"params": {
																"type": "object",
																"description": "Success criterion parameters"
															}
														},
														"required": [
															"type",
															"params"
														]
													}
												}
											},
											"required": [
												"simulationName",
												"personaName",
												"personaDescription",
												"mission",
												"successCriteria"
											]
										},
										"metadata": {
											"type": "object",
											"description": "Optional metadata about the regeneration",
											"properties": {
												"requestId": {
													"type": "string",
													"description": "Request identifier"
												},
												"processedAt": {
													"type": "string",
													"description": "Timestamp when processed"
												},
												"model": {
													"type": "string",
													"description": "LLM model used"
												},
												"regeneratedField": {
													"type": "string",
													"description": "Field that was regenerated"
												},
												"regeneratedIndex": {
													"type": "integer",
													"description": "Index of regenerated success criterion (if applicable)"
												}
											}
										}
									},
									"required": [
										"success",
										"personaPackage"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/personas/generate-bulk": {
			"post": {
				"operationId": "bulkGeneratePersonaPackages",
				"summary": "Bulk generate separated personas and missions",
				"description": "Generate separated persona and mission information for all provided persona types and mission types.\nReturns personas and missions in separated structures for independent management.\n\n**Key Feature**: This endpoint generates ALL combinations of provided persona types and mission types, \nreturning them in a structured format where:\n- Personas are keyed by persona type name\n- Missions are keyed by mission type name\n",
				"tags": [
					"Personas"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier (alternative to projectReference in body)"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"projectReference": {
										"type": "string",
										"description": "Project reference for context identification (alternative to projectId query parameter)"
									},
									"flowReferenceId": {
										"type": "string",
										"description": "Flow reference ID for AI agent and tool discovery"
									},
									"allMissionTypes": {
										"type": "array",
										"description": "All mission types to generate missions for",
										"items": {
											"type": "object",
											"properties": {
												"name": {
													"type": "string",
													"description": "Mission type name"
												},
												"description": {
													"type": "string",
													"description": "Mission type description"
												},
												"successCriteria": {
													"type": "array",
													"description": "Success criteria templates",
													"items": {
														"type": "object",
														"properties": {
															"name": {
																"type": "string"
															},
															"description": {
																"type": "string"
															}
														},
														"required": [
															"name",
															"description"
														]
													}
												}
											},
											"required": [
												"name",
												"description",
												"successCriteria"
											]
										}
									},
									"allPersonaTypes": {
										"type": "array",
										"description": "All persona types to generate personas for",
										"items": {
											"type": "object",
											"properties": {
												"name": {
													"type": "string",
													"description": "Persona type name"
												},
												"description": {
													"type": "string",
													"description": "Persona type description"
												}
											},
											"required": [
												"name",
												"description"
											]
										}
									},
									"numberOfSuccessCriteria": {
										"type": "integer",
										"description": "Number of success criteria to generate per mission",
										"minimum": 1
									},
									"requestedPackages": {
										"type": "integer",
										"description": "Number of packages to generate per type combination",
										"minimum": 1
									}
								},
								"required": [
									"flowReferenceId",
									"allMissionTypes",
									"allPersonaTypes",
									"numberOfSuccessCriteria",
									"requestedPackages"
								]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Bulk personas and missions generated successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"description": "Whether the generation was successful"
										},
										"personas": {
											"type": "object",
											"description": "Personas organized by persona type name as keys",
											"additionalProperties": {
												"type": "array",
												"items": {
													"type": "object",
													"properties": {
														"simulationName": {
															"type": "string",
															"description": "Generated scenario name"
														},
														"personaName": {
															"type": "string",
															"description": "Generated persona name"
														},
														"personaDescription": {
															"type": "string",
															"description": "Generated persona description"
														}
													},
													"required": [
														"simulationName",
														"personaName",
														"personaDescription"
													]
												}
											},
											"example": {
												"Customer Support Agent": [
													{
														"simulationName": "Customer Issue Resolution",
														"personaName": "Sarah",
														"personaDescription": "Experienced support agent..."
													}
												]
											}
										},
										"missions": {
											"type": "object",
											"description": "Missions organized by mission type name as keys",
											"additionalProperties": {
												"type": "array",
												"items": {
													"type": "object",
													"properties": {
														"mission": {
															"type": "string",
															"description": "Generated mission"
														},
														"successCriteria": {
															"type": "array",
															"description": "Generated success criteria",
															"items": {
																"type": "object",
																"properties": {
																	"type": {
																		"type": "string",
																		"description": "Success criterion type"
																	},
																	"params": {
																		"type": "object",
																		"description": "Success criterion parameters"
																	}
																},
																"required": [
																	"type",
																	"params"
																]
															}
														}
													},
													"required": [
														"mission",
														"successCriteria"
													]
												}
											},
											"example": {
												"Technical Support": [
													{
														"mission": "Resolve customer technical issue",
														"successCriteria": [
															{
																"type": "goal",
																"params": {
																	"description": "Issue resolved"
																}
															}
														]
													}
												]
											}
										},
										"metadata": {
											"type": "object",
											"description": "Optional metadata about the generation",
											"properties": {
												"requestId": {
													"type": "string",
													"description": "Request identifier"
												},
												"processedAt": {
													"type": "string",
													"description": "Timestamp when processed"
												},
												"model": {
													"type": "string",
													"description": "LLM model used"
												},
												"personaTypesCount": {
													"type": "integer",
													"description": "Number of persona types processed"
												},
												"missionTypesCount": {
													"type": "integer",
													"description": "Number of mission types processed"
												}
											}
										}
									},
									"required": [
										"success",
										"personas",
										"missions"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/personas/from-transcript": {
			"post": {
				"operationId": "createScenarioFromTranscript",
				"summary": "Create scenario from transcript",
				"description": "Create a scenario draft by analyzing a conversation transcript. The system uses LLM to extract user intent, \nconversation goals, and user characteristics from the transcript, then generates an appropriate persona package.\n\nThe endpoint supports:\n- Fetching transcript via sessionId from analytics service (RPC call)\n- Direct transcript content via transcriptContent\n- Optional flow context for enhanced persona generation\n- Content safety validation (warnings only, non-blocking)\n\nPriority: If both sessionId and transcriptContent are provided, sessionId takes precedence.\n\nReturns a complete persona package and metadata about the analysis.\n",
				"tags": [
					"Personas"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier (alternative to projectReference in body)"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"projectReference": {
										"type": "string",
										"description": "Project reference for context identification (alternative to projectId query parameter)"
									},
									"sessionId": {
										"type": "string",
										"description": "Session identifier to retrieve transcript from analytics service. If provided, takes precedence over transcriptContent."
									},
									"transcriptContent": {
										"type": "object",
										"description": "Direct transcript content. Optional if sessionId is provided.",
										"properties": {
											"messages": {
												"type": "array",
												"description": "Array of conversation messages",
												"items": {
													"type": "object",
													"properties": {
														"source": {
															"type": "string",
															"enum": [
																"user",
																"bot",
																"agent",
																"suggestion"
															],
															"description": "Message source type: 'user' (customer), 'bot' (AI agent), 'agent' (live human agent), 'suggestion' (system suggestion)"
														},
														"content": {
															"type": "string",
															"description": "Message content"
														},
														"timestamp": {
															"type": "string",
															"format": "date-time",
															"description": "Message timestamp"
														}
													},
													"required": [
														"source",
														"content",
														"timestamp"
													]
												}
											}
										},
										"required": [
											"messages"
										]
									},
									"flowId": {
										"type": "string",
										"description": "Optional: Flow ID to associate with and extract agent context for enhanced generation"
									},
									"numberOfSuccessCriteria": {
										"type": "integer",
										"description": "Optional: Number of success criteria to generate (default: 5, min: 1, max: 10)",
										"minimum": 1,
										"maximum": 10,
										"default": 5
									},
									"analysisOptions": {
										"type": "object",
										"description": "Optional analysis configuration",
										"properties": {
											"maxTurns": {
												"type": "integer",
												"description": "Limit transcript to first N turns (default: no limit)",
												"minimum": 1
											},
											"focusOnUserGoals": {
												"type": "boolean",
												"description": "Focus analysis on extracting user goals (default: true)"
											}
										}
									}
								}
							},
							"examples": {
								"withSessionId": {
									"summary": "Request with sessionId (fetches from analytics service)",
									"value": {
										"projectReference": "683ef2a378a878cc6550f78b",
										"sessionId": "session-8f9046b1-6f80-474c-9ce7-24866dbd7cf3",
										"flowId": "683ef3d978a878cc6550fb9d",
										"numberOfSuccessCriteria": 5
									}
								},
								"withTranscriptContent": {
									"summary": "Request with direct transcript content",
									"value": {
										"projectReference": "683ef2a378a878cc6550f78b",
										"transcriptContent": {
											"messages": [
												{
													"source": "user",
													"content": "Hi, I need help unlocking my account",
													"timestamp": "2025-10-22T10:00:00.000Z"
												},
												{
													"source": "bot",
													"content": "I can help you with that. Can you provide your email?",
													"timestamp": "2025-10-22T10:00:05.000Z"
												}
											]
										},
										"flowId": "683ef3d978a878cc6550fb9d",
										"numberOfSuccessCriteria": 5
									}
								}
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Scenario created successfully from transcript",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean",
											"description": "Whether the generation was successful"
										},
										"personaPackage": {
											"type": "object",
											"description": "Generated persona package",
											"properties": {
												"simulationName": {
													"type": "string",
													"description": "Generated scenario name"
												},
												"personaName": {
													"type": "string",
													"description": "Generated persona name"
												},
												"personaDescription": {
													"type": "string",
													"description": "Generated persona description capturing user characteristics"
												},
												"mission": {
													"type": "string",
													"description": "Generated mission based on user goals"
												},
												"successCriteria": {
													"type": "array",
													"description": "Generated success criteria",
													"items": {
														"type": "object",
														"properties": {
															"name": {
																"type": "string",
																"description": "Success criterion name"
															},
															"text": {
																"type": "string",
																"description": "Success criterion description"
															}
														},
														"required": [
															"name",
															"text"
														]
													}
												}
											},
											"required": [
												"simulationName",
												"personaName",
												"personaDescription",
												"mission",
												"successCriteria"
											]
										},
										"metadata": {
											"type": "object",
											"description": "Analysis metadata",
											"properties": {
												"transcriptSummary": {
													"type": "string",
													"description": "Brief summary of the analyzed transcript"
												},
												"analysisTimestamp": {
													"type": "string",
													"format": "date-time",
													"description": "When the analysis was performed"
												},
												"warnings": {
													"type": "array",
													"description": "Content safety warnings (if any)",
													"items": {
														"type": "string"
													}
												},
												"turnCount": {
													"type": "integer",
													"description": "Number of turns in the transcript"
												},
												"extractedIntents": {
													"type": "array",
													"description": "User intents/goals extracted from transcript",
													"items": {
														"type": "string"
													}
												},
												"messages": {
													"type": "array",
													"description": "Original transcript messages",
													"items": {
														"type": "object",
														"properties": {
															"source": {
																"type": "string",
																"enum": [
																	"user",
																	"bot",
																	"agent",
																	"suggestion"
																],
																"description": "Message source"
															},
															"content": {
																"type": "string",
																"description": "Message content"
															},
															"timestamp": {
																"type": "string",
																"format": "date-time",
																"description": "Message timestamp"
															}
														},
														"required": [
															"source",
															"content",
															"timestamp"
														]
													}
												}
											},
											"required": [
												"transcriptSummary",
												"analysisTimestamp",
												"messages"
											]
										}
									},
									"required": [
										"success",
										"personaPackage",
										"metadata"
									]
								},
								"example": {
									"success": true,
									"personaPackage": {
										"simulationName": "Account Unlock Request",
										"personaName": "Frustrated Traveler",
										"personaDescription": "A business traveler who is tech-savvy but stressed due to being locked out of their account before an important flight. Communicates directly and expects quick resolutions.",
										"mission": "Unlock the account quickly to access booking information for an upcoming flight",
										"successCriteria": [
											{
												"name": "Account Unlocked",
												"text": "User successfully regains access to their account"
											},
											{
												"name": "Booking Confirmed",
												"text": "User can view and confirm their flight booking details"
											},
											{
												"name": "Security Verified",
												"text": "Account security is verified and strengthened"
											}
										]
									},
									"metadata": {
										"transcriptSummary": "8-turn conversation (4 user, 4 bot): \"Hi, I need help unlocking my account. I have a flight in 2 hours...\"",
										"analysisTimestamp": "2024-10-22T10:00:43.000Z",
										"warnings": [],
										"turnCount": 8,
										"extractedIntents": [
											"Unlock account",
											"Access flight booking",
											"Verify travel details"
										],
										"messages": [
											{
												"source": "user",
												"content": "Hi, I need help unlocking my account. I have a flight in 2 hours and I cannot access my booking.",
												"timestamp": "2024-10-22T10:00:00.000Z"
											},
											{
												"source": "bot",
												"content": "Hello! I can help you unlock your account. Can you please provide me with your email address?",
												"timestamp": "2024-10-22T10:00:05.000Z"
											},
											{
												"source": "user",
												"content": "My email is traveler@example.com",
												"timestamp": "2024-10-22T10:00:15.000Z"
											},
											{
												"source": "bot",
												"content": "Thank you. I have found your account. For security purposes, can you verify your date of birth?",
												"timestamp": "2024-10-22T10:00:20.000Z"
											},
											{
												"source": "user",
												"content": "January 15, 1985",
												"timestamp": "2024-10-22T10:00:30.000Z"
											},
											{
												"source": "bot",
												"content": "Perfect. Your account has been unlocked. You should now be able to access your booking.",
												"timestamp": "2024-10-22T10:00:35.000Z"
											},
											{
												"source": "user",
												"content": "Thank you! Can you confirm my flight details?",
												"timestamp": "2024-10-22T10:00:45.000Z"
											},
											{
												"source": "bot",
												"content": "Your flight is scheduled for today at 12:00 PM, Flight AB123 to New York.",
												"timestamp": "2024-10-22T10:00:50.000Z"
											}
										]
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										}
									},
									"required": [
										"error"
									]
								},
								"examples": {
									"missingTranscript": {
										"value": {
											"error": "One of sessionId or transcriptContent is required"
										}
									},
									"invalidMessages": {
										"value": {
											"error": "transcriptContent.messages must be an array"
										}
									},
									"emptyTranscript": {
										"value": {
											"error": "Transcript must contain at least one message"
										}
									},
									"invalidSource": {
										"value": {
											"error": "Message source must be one of: user, bot, agent, suggestion"
										}
									},
									"transcriptTooShort": {
										"value": {
											"error": "Transcript must contain at least 2 messages, got 1"
										}
									},
									"invalidSessionId": {
										"value": {
											"error": "sessionId must be a non-empty string"
										}
									},
									"sessionNotFound": {
										"value": {
											"error": "No valid transcript messages found for session session-xyz. The conversation may be empty or contain only system messages."
										}
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/dashboard/overview": {
			"get": {
				"operationId": "getDashboardOverview",
				"summary": "Get dashboard overview metrics",
				"description": "Retrieve key metrics for the dashboard overview cards including total scenarios, simulations, average success rate, and scheduled runs count.",
				"tags": [
					"Dashboard"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"name": "scenarioIds",
						"in": "query",
						"required": false,
						"schema": {
							"type": "array",
							"items": {
								"type": "string"
							}
						},
						"style": "form",
						"explode": false,
						"description": "Filter by scenario/simulation reference IDs (comma-separated or array). If not provided, includes all scenarios.",
						"example": [
							"sim-ref-1",
							"sim-ref-2"
						]
					},
					{
						"name": "timeWindow",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string",
							"enum": [
								"7d",
								"30d",
								"3m"
							],
							"default": "7d"
						},
						"description": "Time window for data aggregation. Options: 7d (last 7 days), 30d (last 30 days), 3m (last 3 months)"
					}
				],
				"responses": {
					"200": {
						"description": "Dashboard overview metrics retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"totalScenarios": {
											"type": "integer",
											"description": "Count of all active test scenarios (simulations)",
											"example": 15
										},
										"totalSimulations": {
											"type": "integer",
											"description": "Number of completed simulation runs (manual + scheduled) within the time window",
											"example": 142
										},
										"avgSuccessRate": {
											"type": "number",
											"format": "float",
											"minimum": 0,
											"maximum": 100,
											"description": "Average success rate across all recent simulations (weighted by number of runs) within the time window",
											"example": 87.5
										},
										"scheduledRuns": {
											"type": "integer",
											"description": "Count of currently active schedules (simulations with status IN_PROGRESS)",
											"example": 8
										}
									},
									"required": [
										"totalScenarios",
										"totalSimulations",
										"avgSuccessRate",
										"scheduledRuns"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/dashboard/success-rate-trend": {
			"get": {
				"operationId": "getDashboardSuccessRateTrend",
				"summary": "Get success rate trend data",
				"description": "Retrieve 7-day rolling average trend of simulation outcomes for visualization. Returns daily aggregated data showing successful vs failed runs.",
				"tags": [
					"Dashboard"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"name": "scenarioIds",
						"in": "query",
						"required": false,
						"schema": {
							"type": "array",
							"items": {
								"type": "string"
							}
						},
						"style": "form",
						"explode": false,
						"description": "Filter by scenario/simulation reference IDs (comma-separated or array). If not provided, includes all scenarios.",
						"example": [
							"sim-ref-1",
							"sim-ref-2"
						]
					},
					{
						"name": "timeWindow",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string",
							"enum": [
								"7d",
								"30d",
								"3m"
							],
							"default": "7d"
						},
						"description": "Time window for data aggregation. Options: 7d (last 7 days), 30d (last 30 days), 3m (last 3 months)"
					}
				],
				"responses": {
					"200": {
						"description": "Success rate trend data retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": {
											"type": "array",
											"description": "Array of daily trend data points",
											"items": {
												"type": "object",
												"properties": {
													"date": {
														"type": "string",
														"format": "date",
														"description": "Date for this data point (YYYY-MM-DD)",
														"example": "2024-01-15"
													},
													"totalRuns": {
														"type": "integer",
														"description": "Total number of simulation runs on this date",
														"example": 25
													},
													"successfulRuns": {
														"type": "integer",
														"description": "Number of successful runs on this date",
														"example": 22
													},
													"failedRuns": {
														"type": "integer",
														"description": "Number of failed runs on this date",
														"example": 3
													},
													"successPercentage": {
														"type": "number",
														"format": "float",
														"minimum": 0,
														"maximum": 100,
														"description": "Percentage of successful runs (same as successRate, for convenience)",
														"example": 88
													}
												},
												"required": [
													"date",
													"totalRuns",
													"successfulRuns",
													"failedRuns",
													"successRate",
													"successPercentage"
												]
											}
										}
									},
									"required": [
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/dashboard/upcoming-scheduled-runs": {
			"get": {
				"operationId": "getDashboardUpcomingScheduledRuns",
				"summary": "Get upcoming scheduled runs",
				"description": "Retrieve list of upcoming scheduled simulation runs with scenario name, next run time, and frequency information.",
				"tags": [
					"Dashboard"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": true,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					},
					{
						"name": "scenarioIds",
						"in": "query",
						"required": false,
						"schema": {
							"type": "array",
							"items": {
								"type": "string"
							}
						},
						"style": "form",
						"explode": false,
						"description": "Filter by scenario/simulation reference IDs (comma-separated or array). If not provided, includes all scenarios.",
						"example": [
							"sim-ref-1",
							"sim-ref-2"
						]
					},
					{
						"name": "limit",
						"in": "query",
						"required": false,
						"schema": {
							"type": "integer",
							"minimum": 1,
							"maximum": 100,
							"default": 20
						},
						"description": "Maximum number of upcoming scheduled runs to return"
					}
				],
				"responses": {
					"200": {
						"description": "Upcoming scheduled runs retrieved successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"data": {
											"type": "array",
											"description": "Array of upcoming scheduled runs",
											"items": {
												"type": "object",
												"properties": {
													"simulationReference": {
														"type": "string",
														"description": "Reference ID of the simulation/scenario",
														"example": "sim-ref-123"
													},
													"simulationName": {
														"type": "string",
														"description": "Name of the scenario/simulation",
														"example": "Customer Support Flow Test"
													},
													"nextRun": {
														"type": "string",
														"format": "date-time",
														"description": "ISO 8601 date/time of the next scheduled run",
														"example": "2024-01-20T10:00:00Z"
													},
													"frequency": {
														"type": "string",
														"enum": [
															"Daily",
															"Every 3 days",
															"Weekly",
															"Bi-weekly",
															"Monthly"
														],
														"description": "Frequency tag for the schedule",
														"example": "Daily"
													},
													"frequencyValue": {
														"type": "string",
														"description": "Raw frequency value from the schedule (for reference)",
														"example": "0 10 * * *"
													},
													"batchId": {
														"type": "string",
														"description": "ID of the simulation associated with this schedule",
														"example": "batch-id-456"
													},
													"batchName": {
														"type": "string",
														"description": "Name of the simulation",
														"example": "Daily Customer Support Test"
													},
													"status": {
														"type": "string",
														"enum": [
															"IN_PROGRESS",
															"STOPPED",
															"COMPLETED",
															"FAILED"
														],
														"description": "Status of the scheduled simulation",
														"example": "IN_PROGRESS"
													}
												},
												"required": [
													"simulationReference",
													"simulationName",
													"nextRun",
													"frequency",
													"batchId",
													"status"
												]
											}
										}
									},
									"required": [
										"data"
									]
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid input parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Validation error message"
										},
										"field": {
											"type": "string",
											"description": "Field that failed validation"
										},
										"code": {
											"type": "string",
											"description": "Validation error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error",
										"field"
									]
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized - Invalid or missing authentication",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Unauthorized error message"
										},
										"code": {
											"type": "string",
											"description": "Unauthorized error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"403": {
						"description": "Forbidden - Insufficient permissions",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Forbidden error message"
										},
										"code": {
											"type": "string",
											"description": "Forbidden error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"500": {
						"description": "Internal Server Error - Server error",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string",
											"description": "Error message"
										},
										"code": {
											"type": "string",
											"description": "Error code"
										},
										"traceId": {
											"type": "string",
											"description": "Trace ID for debugging"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/v1/transcript-request": {
			"post": {
				"operationId": "createTranscriptRequest",
				"summary": "Create transcript upload request",
				"description": "Create a new transcript upload session. This is the first step in the three-step workflow\nfor generating scenarios from transcript files.\n\nThis endpoint:\n- Creates a new request with a unique ID\n- Checks rate limits per project (max active requests)\n- Returns configuration details (max files, max file size, supported formats)\n\nThe returned requestId must be passed in subsequent upload and generation calls.\n\n**projectId is required.** Provide it via the `project_id` header, or in the request body/query.\n",
				"tags": [
					"Transcript Scenario Generation"
				],
				"parameters": [
					{
						"name": "project_id",
						"in": "header",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier. Use this header to pass projectId; alternatively use body or query."
					},
					{
						"name": "projectId",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier (alternative to project_id header or projectReference in body)"
					}
				],
				"requestBody": {
					"required": false,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"projectId": {
										"type": "string",
										"description": "Project identifier (alternative to project_id header)"
									},
									"projectReference": {
										"type": "string",
										"description": "Alternative project reference"
									}
								}
							},
							"examples": {
								"basic": {
									"summary": "Create transcript request (with header project_id)",
									"value": {}
								},
								"withBody": {
									"summary": "Create transcript request with body projectId",
									"value": {
										"projectId": "683ef2a378a878cc6550f78b"
									}
								}
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Transcript request created successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"requestId": {
											"type": "string",
											"description": "Unique request identifier for subsequent calls"
										},
										"expiresAt": {
											"type": "string",
											"format": "date-time",
											"description": "When this request will expire"
										},
										"maxFiles": {
											"type": "integer",
											"description": "Maximum number of files that can be uploaded"
										},
										"maxFileSize": {
											"type": "integer",
											"description": "Maximum file size in bytes"
										},
										"maxTotalSize": {
											"type": "integer",
											"description": "Maximum total upload size in bytes"
										},
										"supportedFormats": {
											"type": "array",
											"items": {
												"type": "string"
											},
											"description": "Supported file formats"
										},
										"status": {
											"type": "string",
											"enum": [
												"pending"
											],
											"description": "Request status"
										}
									},
									"required": [
										"success",
										"requestId",
										"expiresAt",
										"maxFiles",
										"maxFileSize",
										"supportedFormats",
										"status"
									]
								},
								"example": {
									"success": true,
									"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
									"expiresAt": "2026-02-08T15:00:00.000Z",
									"maxFiles": 5,
									"maxFileSize": 10485760,
									"maxTotalSize": 52428800,
									"supportedFormats": [
										"application/pdf",
										"text/csv",
										"application/vnd.openxmlformats-officedocument.wordprocessingml.document"
									],
									"status": "pending"
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - projectId is required (provide via project_id header, or in body/query)",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										}
									}
								},
								"example": {
									"error": "projectId is required (in body, query, or as projectReference)"
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized"
					},
					"403": {
						"description": "Forbidden - Insufficient permissions"
					},
					"429": {
						"description": "Too Many Requests - Rate limit exceeded",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								},
								"example": {
									"error": "Maximum of 10 active transcript requests reached for this project."
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/v1/transcript-upload": {
			"post": {
				"operationId": "uploadTranscriptFile",
				"summary": "Upload and parse a transcript file",
				"description": "Upload a single transcript file for parsing and content extraction. This is the second step\nin the three-step workflow.\n\nThe file is streamed directly to Redis via the streamUpload middleware, then:\n1. Read back from Redis\n2. Parsed based on file type (PDF, CSV, DOCX)\n3. Analyzed for speaker labels (Agent/Customer)\n4. Stored as structured data in Redis (keyed by requestId)\n\nMultiple files can be uploaded by calling this endpoint multiple times with the same requestId.\nThe generate endpoint retrieves all files for the request by requestId.\n",
				"tags": [
					"Transcript Scenario Generation"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"multipart/form-data": {
							"schema": {
								"type": "object",
								"properties": {
									"requestId": {
										"type": "string",
										"description": "Request ID from the create-request step"
									},
									"projectId": {
										"type": "string",
										"description": "Project identifier"
									},
									"transcript": {
										"type": "string",
										"format": "binary",
										"description": "Transcript file (PDF, CSV, or DOCX)"
									}
								},
								"required": [
									"requestId",
									"transcript"
								]
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "File uploaded and parsed successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"fileId": {
											"type": "string",
											"description": "Unique file identifier"
										},
										"fileName": {
											"type": "string",
											"description": "Original file name"
										},
										"fileSize": {
											"type": "integer",
											"description": "File size in bytes"
										},
										"fileType": {
											"type": "string",
											"enum": [
												"pdf",
												"csv",
												"docx"
											],
											"description": "Detected file type"
										},
										"textLength": {
											"type": "integer",
											"description": "Length of extracted text content"
										},
										"processedAt": {
											"type": "string",
											"format": "date-time"
										}
									},
									"required": [
										"success",
										"fileId",
										"fileName",
										"fileSize",
										"fileType",
										"textLength",
										"processedAt"
									]
								},
								"example": {
									"success": true,
									"fileId": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
									"fileName": "customer_support_call.pdf",
									"fileSize": 245678,
									"fileType": "pdf",
									"textLength": 2450,
									"processedAt": "2026-02-08T14:30:00.000Z"
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid file or missing parameters",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								},
								"examples": {
									"missingFile": {
										"value": {
											"error": "No file was uploaded. Please include a file in the request."
										}
									},
									"unsupportedType": {
										"value": {
											"error": "Unsupported file type 'text/plain'. Supported types: pdf, csv, docx"
										}
									},
									"noSpeakerLabels": {
										"value": {
											"error": "Speaker labels not detected. All transcripts must contain clear Agent/Customer speaker labels."
										}
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized"
					},
					"403": {
						"description": "Forbidden - Insufficient permissions"
					},
					"404": {
						"description": "Not Found - Request ID not found or expired",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								},
								"example": {
									"error": "Transcript request not found or has expired. Please create a new request."
								}
							}
						}
					},
					"413": {
						"description": "Payload Too Large - File exceeds maximum size"
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		},
		"/v1/generate-from-transcript": {
			"post": {
				"operationId": "generateFromTranscript",
				"summary": "Generate scenarios from uploaded transcripts",
				"description": "Generate 3 distinct simulation scenarios from previously uploaded and parsed transcript files.\nThis is the third and final step in the three-step workflow.\n\nThe endpoint:\n1. Retrieves all uploaded files from Redis for the given requestId\n2. Combines all transcript content\n3. Validates minimum word count\n4. Calls the LLM via RPC to generate 3 scenarios\n5. Cleans up Redis data after successful generation\n\nEach generated scenario includes a simulationName, personaName, personaDescription,\nmission, and success criteria - ready to be used for creating simulations.\n",
				"tags": [
					"Transcript Scenario Generation"
				],
				"parameters": [
					{
						"name": "projectId",
						"in": "query",
						"required": false,
						"schema": {
							"type": "string"
						},
						"description": "Project identifier"
					}
				],
				"requestBody": {
					"required": true,
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"properties": {
									"projectId": {
										"type": "string",
										"description": "Project identifier"
									},
									"requestId": {
										"type": "string",
										"description": "Request ID from the create-request step (all files uploaded for this request are used)"
									},
									"flowReference": {
										"type": "string",
										"pattern": "^[a-fA-F0-9]{24}$",
										"description": "Optional flow reference (MongoDB ObjectId) for context-aware generation"
									},
									"numberOfSuccessCriteria": {
										"type": "integer",
										"minimum": 1,
										"maximum": 10,
										"description": "Number of success criteria per scenario (required, 1-10)"
									}
								},
								"required": [
									"requestId",
									"numberOfSuccessCriteria"
								]
							},
							"example": {
								"projectId": "683ef2a378a878cc6550f78b",
								"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
								"flowReference": "683ef3d978a878cc6550fb9d",
								"numberOfSuccessCriteria": 3
							}
						}
					}
				},
				"responses": {
					"200": {
						"description": "Scenarios generated successfully",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"success": {
											"type": "boolean"
										},
										"scenarios": {
											"type": "array",
											"description": "3 generated simulation scenarios",
											"items": {
												"type": "object",
												"properties": {
													"simulationName": {
														"type": "string",
														"description": "Descriptive name for the simulation"
													},
													"personaName": {
														"type": "string",
														"description": "Role-based persona name"
													},
													"personaDescription": {
														"type": "string",
														"description": "Detailed persona behavioral profile"
													},
													"mission": {
														"type": "string",
														"description": "Clear, testable mission objective"
													},
													"successCriteria": {
														"type": "array",
														"items": {
															"type": "object",
															"properties": {
																"type": {
																	"type": "string",
																	"enum": [
																		"text",
																		"goalCompleted"
																	]
																},
																"params": {
																	"type": "object",
																	"properties": {
																		"name": {
																			"type": "string"
																		},
																		"text": {
																			"type": "string"
																		}
																	},
																	"required": [
																		"name",
																		"text"
																	]
																}
															}
														},
														"description": "Measurable success criteria"
													}
												},
												"required": [
													"simulationName",
													"personaName",
													"personaDescription",
													"mission",
													"successCriteria"
												]
											}
										},
										"metadata": {
											"type": "object",
											"properties": {
												"requestId": {
													"type": "string"
												},
												"filesProcessed": {
													"type": "integer"
												},
												"totalTextLength": {
													"type": "integer"
												},
												"model": {
													"type": "string"
												},
												"processedAt": {
													"type": "string",
													"format": "date-time"
												},
												"generationTimeMs": {
													"type": "integer"
												}
											}
										}
									},
									"required": [
										"success",
										"scenarios",
										"metadata"
									]
								},
								"example": {
									"success": true,
									"scenarios": [
										{
											"simulationName": "Order Status Inquiry",
											"personaName": "Impatient Online Shopper",
											"personaDescription": "A busy professional who ordered a product 3 days ago and hasn't received shipping updates. They are growing increasingly frustrated and want immediate answers.",
											"mission": "Get a definitive answer about the order status and expected delivery date",
											"successCriteria": [
												{
													"type": "text",
													"params": {
														"name": "Order Located",
														"text": "The agent successfully locates and identifies the customer's order"
													}
												},
												{
													"type": "text",
													"params": {
														"name": "Status Communicated",
														"text": "The current shipping status is clearly communicated to the customer"
													}
												},
												{
													"type": "text",
													"params": {
														"name": "Delivery Date Provided",
														"text": "An expected delivery date is provided to the customer"
													}
												}
											]
										},
										{
											"simulationName": "Return Process Assistance",
											"personaName": "Confused Return Requester",
											"personaDescription": "A customer who received a damaged item and wants to return it but is unfamiliar with the return process. They need step-by-step guidance.",
											"mission": "Successfully initiate a return for a damaged item and understand the refund timeline",
											"successCriteria": [
												{
													"type": "text",
													"params": {
														"name": "Return Initiated",
														"text": "A return request is successfully created for the damaged item"
													}
												},
												{
													"type": "text",
													"params": {
														"name": "Process Explained",
														"text": "The return process steps are clearly explained to the customer"
													}
												},
												{
													"type": "text",
													"params": {
														"name": "Refund Timeline",
														"text": "The expected refund timeline is communicated"
													}
												}
											]
										},
										{
											"simulationName": "Account Access Recovery",
											"personaName": "Locked Out Account Holder",
											"personaDescription": "A long-time customer who has been locked out of their account after multiple failed login attempts. They are anxious about accessing recent purchase history.",
											"mission": "Regain access to the locked account and verify recent purchase information",
											"successCriteria": [
												{
													"type": "text",
													"params": {
														"name": "Identity Verified",
														"text": "The customer's identity is verified through security questions"
													}
												},
												{
													"type": "text",
													"params": {
														"name": "Account Unlocked",
														"text": "The account is successfully unlocked and access is restored"
													}
												},
												{
													"type": "text",
													"params": {
														"name": "Purchase History",
														"text": "The customer can access their recent purchase history"
													}
												}
											]
										}
									],
									"metadata": {
										"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
										"filesProcessed": 2,
										"totalTextLength": 4500,
										"model": "default",
										"processedAt": "2026-02-08T14:35:00.000Z",
										"generationTimeMs": 12500
									}
								}
							}
						}
					},
					"400": {
						"description": "Bad Request - Invalid parameters or insufficient content",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								},
								"examples": {
									"missingRequestId": {
										"value": {
											"error": "requestId is required"
										}
									},
									"invalidSuccessCriteria": {
										"value": {
											"error": "numberOfSuccessCriteria is required and must be a number between 1 and 10"
										}
									},
									"insufficientContent": {
										"value": {
											"error": "Insufficient transcript content: 50 words found (minimum: 100)"
										}
									}
								}
							}
						}
					},
					"401": {
						"description": "Unauthorized"
					},
					"403": {
						"description": "Forbidden - Insufficient permissions"
					},
					"404": {
						"description": "Not Found - Request or file not found",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								}
							}
						}
					},
					"504": {
						"description": "Gateway Timeout - Generation timed out",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"error": {
											"type": "string"
										}
									},
									"required": [
										"error"
									]
								},
								"example": {
									"error": "Scenario generation timed out. Your uploaded files are still available for retry."
								}
							}
						}
					}
				},
				"security": [
					{
						"bearerAuth": []
					},
					{
						"apiKeyAuth": []
					}
				]
			}
		}
	},
	"servers": [
		{
			"url": "https://api-trial.cognigy.ai/testing",
			"description": "Cognigy Service Testing API"
		}
	]
}