> For the complete documentation index, see [llms.txt](https://docs-conversational-ai.syntphony.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-conversational-ai.syntphony.com/api-docs/api-guidelines/management-api/instance-api/generative-service.md).

# Generative Service

The Generative Service API handles all integration with LLMs and generative content.

{% hint style="info" %}
**API SUBPATH**: eva-generative-service
{% endhint %}

### Pagination and Listing

## GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service

> Searches and paginates through expected Generative Service

```json
{"openapi":"3.1.0","info":{"title":"eva-generative-service API Documentation","version":"4.9.0"},"tags":[{"name":"Generative Service Controller","description":"Management for creating, listing, finding, updating and deleting Generative Services"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service":{"get":{"tags":["Generative Service Controller"],"summary":"Searches and paginates through expected Generative Service","operationId":"findAll","parameters":[{"name":"searchTerm","in":"query","description":"Term being searched. This expects an optional String matching the name of a generativeService.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Current page, starting at 1","required":true,"schema":{"type":"integer","format":"int32","default":1}},{"name":"size","in":"query","description":"Number of items per page","required":true,"schema":{"type":"integer","format":"int32","default":5}},{"name":"orgUUID","in":"path","description":"A valid UUID of an organization","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid UUID of an environment","required":true,"schema":{"type":"string"}},{"name":"botUUID","in":"path","description":"The UUID of the bot whose entities you are searching","required":true,"schema":{"type":"string"}},{"name":"orderBy","in":"query","description":"Criteria to sort results, defaulted to 'updatedAt'. Possible fields include name, createdAt, updatedAt, createdBy, and updatedBy.","required":false,"schema":{"type":"string","default":"updatedAt"}},{"name":"direction","in":"query","description":"Sort direction (ASC/DESC), defaulted to DESC.","required":false,"schema":{"type":"string","default":"DESC"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageGenerativeServiceFlowsDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"PageGenerativeServiceFlowsDTO":{"type":"object","properties":{"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"},"pageable":{"$ref":"#/components/schemas/PageableObject"},"numberOfElements":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"content":{"type":"array","items":{"$ref":"#/components/schemas/GenerativeServiceFlowsDTO"}},"number":{"type":"integer","format":"int32"},"sort":{"$ref":"#/components/schemas/SortObject"},"first":{"type":"boolean"},"last":{"type":"boolean"},"empty":{"type":"boolean"}}},"PageableObject":{"type":"object","properties":{"paged":{"type":"boolean"},"pageNumber":{"type":"integer","format":"int32"},"pageSize":{"type":"integer","format":"int32"},"unpaged":{"type":"boolean"},"offset":{"type":"integer","format":"int64"},"sort":{"$ref":"#/components/schemas/SortObject"}}},"SortObject":{"type":"object","properties":{"sorted":{"type":"boolean"},"unsorted":{"type":"boolean"},"empty":{"type":"boolean"}}},"GenerativeServiceFlowsDTO":{"type":"object","description":"A Structure holding a mapping of an Generative Service's information and all Flows associated to it.","properties":{"generativeService":{"$ref":"#/components/schemas/GenerativeServiceDTO","description":"All data regarding this Generative Service"},"flows":{"type":"array","description":"A list of Flows associated to this Generative Service","items":{"$ref":"#/components/schemas/FlowResponseDTO"}}}},"GenerativeServiceDTO":{"type":"object","description":"A Structure representing all data of a Generative Service.","properties":{"uuid":{"type":"string","description":"Uuid of this Generative Service."},"name":{"type":"string","description":"Name of this Generative Service."},"description":{"type":"string","description":"An optional description of this Generative Service."},"prompt":{"type":"string","description":"Actual prompt to be executed during AI generation when executing this service."},"model":{"type":"string","description":"AI Model to be used in this Generative Service."},"verbosity":{"type":"string","description":"Response verbosity for GPT-5 series models (LOW, MEDIUM, HIGH).","enum":["LOW","MEDIUM","HIGH"]},"reasoningEffort":{"type":"string","description":"Reasoning effort for GPT-5 series models (MINIMAL, LOW, MEDIUM, HIGH).","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]},"parameterCapabilities":{"$ref":"#/components/schemas/ParameterCapabilitiesDTO","description":"Read-only parameter capabilities for the persisted model (allowed values and defaults)","readOnly":true},"temperature":{"type":"number","format":"double","description":"AI's temperature value for execution of this Generative Service."},"maximumTokens":{"type":"integer","format":"int32","description":"Maximum tokens to be used during a single execution of this Generative Service."},"topP":{"type":"number","format":"double","description":"AI's topP value for execution of this Generative Service."},"presencePenalty":{"type":"number","format":"double","description":"AI's presence penalty value for execution of this Generative Service."},"frequencyPenalty":{"type":"number","format":"double","description":"AI's frequency penalty value for execution of this Generative Service."},"responseVariableName":{"type":"string","description":"Name of the variable in $hiddenContext this service will store it's result."},"usesBlacklist":{"type":"boolean","description":"Wether this execution should blacklist specific words."},"blacklistWords":{"type":"string","description":"A blacklist of comma-separated terms to be excluded from this service's generation."},"removed":{"type":"boolean","description":"Wether this service is logically excluded."},"createdAt":{"type":"string","format":"date-time","description":"An ISO formatted date of the creation of this Generative Service."},"updatedAt":{"type":"string","format":"date-time","description":"An ISO formatted date of the last update of this Generative Service."},"updatedBy":{"type":"string","description":"Uuid of the user that has last updated this Generative Service."},"createdBy":{"type":"string","description":"Uuid of the user that initially created this Generative Service."}}},"ParameterCapabilitiesDTO":{"type":"object","description":"Read-only parameter capabilities for the bot model","properties":{"family":{"type":"string","description":"Parameter family for the bot model","enum":["GPT_4","GPT_5"]},"model":{"type":"string","description":"Bot model name used to resolve capabilities"},"verbosity":{"$ref":"#/components/schemas/ParameterEnumCapabilityDTOVerbosity","description":"Verbosity allowed values and default; null for GPT-4"},"reasoningEffort":{"$ref":"#/components/schemas/ParameterEnumCapabilityDTOReasoningEffort","description":"Reasoning effort allowed values and default; null for GPT-4"}}},"ParameterEnumCapabilityDTOVerbosity":{"type":"object","description":"Allowed values and default for a model parameter enum","properties":{"allowed":{"type":"array","description":"Values allowed for the bot model version","items":{"type":"string","enum":["LOW","MEDIUM","HIGH"]}},"defaultValue":{"type":"string","description":"Default when the field is omitted on write","enum":["LOW","MEDIUM","HIGH"]}},"required":["allowed","defaultValue"]},"ParameterEnumCapabilityDTOReasoningEffort":{"type":"object","description":"Allowed values and default for a model parameter enum","properties":{"allowed":{"type":"array","description":"Values allowed for the bot model version","items":{"type":"string","description":"Reasoning effort for GPT-5 series. Allowed values depend on the bot model version.","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]}},"defaultValue":{"type":"string","description":"Default when the field is omitted on write","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]}},"required":["allowed","defaultValue"]},"FlowResponseDTO":{"type":"object","description":"Structure representing a flow's basic information.","properties":{"uuid":{"type":"string","description":"Uuid of the flow."},"name":{"type":"string","description":"Name of the flow"}}},"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}}
```

## GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service/quicksearch

> Searches (greedily) for any Generative Service names that exist in a bot, matching the typed term from left-to-right, and returns a list of strings, ordered alphabetically.

```json
{"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Generative Service Controller","description":"Management for creating, listing, finding, updating and deleting Generative Services"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service/quicksearch":{"get":{"tags":["Generative Service Controller"],"summary":"Searches (greedily) for any Generative Service names that exist in a bot, matching the typed term from left-to-right, and returns a list of strings, ordered alphabetically.","operationId":"autocompleteSearch","parameters":[{"name":"orgUUID","in":"path","description":"A valid organization UUID","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid environment UUID","required":true,"schema":{"type":"string"}},{"name":"botUUID","in":"path","description":"A valid bot UUID to search","required":true,"schema":{"type":"string"}},{"name":"searchTerm","in":"query","description":"The term being searched","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"The maximum number of items to be returned in the list. Defaults to 6.","required":false,"schema":{"type":"integer","format":"int32","default":6}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}}
```

## GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service/list-on-flow

> Retrieves a list of Generative Services recently used on a given bot to start a flow.

```json
{"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Generative Service Controller","description":"Management for creating, listing, finding, updating and deleting Generative Services"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service/list-on-flow":{"get":{"tags":["Generative Service Controller"],"summary":"Retrieves a list of Generative Services recently used on a given bot to start a flow.","operationId":"listOnFlow","parameters":[{"name":"orgUUID","in":"path","description":"A valid UUID of an organization","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid UUID of an environment","required":true,"schema":{"type":"string"}},{"name":"botUUID","in":"path","description":"The UUID of the bot whose entities are being searched","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GenerativeServiceListByFlowDTO"}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"GenerativeServiceListByFlowDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"The Generative Service's String uuid."},"name":{"type":"string","description":"The Generative Service's name."},"model":{"type":"string","description":"The Generative Service's model."}},"description":"A simplified structure holding a shortened mapping of an Generative Service's information and all Flows associated to it."},"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}}
```

### CRUD Operations

## POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service

> Creates a brand new Generative Service

```json
{"openapi":"3.1.0","info":{"title":"eva-generative-service API Documentation","version":"4.9.0"},"tags":[{"name":"Generative Service Controller","description":"Management for creating, listing, finding, updating and deleting Generative Services"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service":{"post":{"tags":["Generative Service Controller"],"summary":"Creates a brand new Generative Service","operationId":"createGenerativeService","parameters":[{"name":"orgUUID","in":"path","description":"A valid UUID of the organization","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid UUID of the environment","required":true,"schema":{"type":"string"}},{"name":"botUUID","in":"path","description":"A valid UUID of the bot","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerativeServiceRequestDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerativeServiceFlowsDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"GenerativeServiceRequestDTO":{"type":"object","description":"Contract required to request the creation of a Generative Service.","properties":{"name":{"type":"string","description":"Name of this Generative Service."},"description":{"type":"string","description":"An optional description of this Generative Service."},"prompt":{"type":"string","description":"Actual prompt to be executed during AI generation when executing this service."},"model":{"type":"string","description":"AI Model to be used in this Generative Service."},"verbosity":{"type":"string","description":"Response verbosity for GPT-5 series models (LOW, MEDIUM, HIGH).","enum":["LOW","MEDIUM","HIGH"]},"reasoningEffort":{"type":"string","description":"Reasoning effort for GPT-5 series models (MINIMAL, LOW, MEDIUM, HIGH).","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]},"temperature":{"type":"number","format":"double","description":"AI's temperature value for execution of this Generative Service."},"maximumTokens":{"type":"integer","format":"int32","description":"Maximum tokens to be used during a single execution of this Generative Service."},"topP":{"type":"number","format":"double","description":"AI's topP value for execution of this Generative Service."},"presencePenalty":{"type":"number","format":"double","description":"AI's presence penalty value for execution of this Generative Service."},"frequencyPenalty":{"type":"number","format":"double","description":"AI's frequency penalty value for execution of this Generative Service."},"responseVariableName":{"type":"string","description":"Name of the variable in $hiddenContext this service will store it's result."},"usesBlacklist":{"type":"boolean","description":"Whether this execution should blacklist specific words."},"blacklistWords":{"type":"string","description":"A blacklist of comma-separated terms to be excluded from this service's generation."}},"required":["name"]},"GenerativeServiceFlowsDTO":{"type":"object","description":"A Structure holding a mapping of an Generative Service's information and all Flows associated to it.","properties":{"generativeService":{"$ref":"#/components/schemas/GenerativeServiceDTO","description":"All data regarding this Generative Service"},"flows":{"type":"array","description":"A list of Flows associated to this Generative Service","items":{"$ref":"#/components/schemas/FlowResponseDTO"}}}},"GenerativeServiceDTO":{"type":"object","description":"A Structure representing all data of a Generative Service.","properties":{"uuid":{"type":"string","description":"Uuid of this Generative Service."},"name":{"type":"string","description":"Name of this Generative Service."},"description":{"type":"string","description":"An optional description of this Generative Service."},"prompt":{"type":"string","description":"Actual prompt to be executed during AI generation when executing this service."},"model":{"type":"string","description":"AI Model to be used in this Generative Service."},"verbosity":{"type":"string","description":"Response verbosity for GPT-5 series models (LOW, MEDIUM, HIGH).","enum":["LOW","MEDIUM","HIGH"]},"reasoningEffort":{"type":"string","description":"Reasoning effort for GPT-5 series models (MINIMAL, LOW, MEDIUM, HIGH).","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]},"parameterCapabilities":{"$ref":"#/components/schemas/ParameterCapabilitiesDTO","description":"Read-only parameter capabilities for the persisted model (allowed values and defaults)","readOnly":true},"temperature":{"type":"number","format":"double","description":"AI's temperature value for execution of this Generative Service."},"maximumTokens":{"type":"integer","format":"int32","description":"Maximum tokens to be used during a single execution of this Generative Service."},"topP":{"type":"number","format":"double","description":"AI's topP value for execution of this Generative Service."},"presencePenalty":{"type":"number","format":"double","description":"AI's presence penalty value for execution of this Generative Service."},"frequencyPenalty":{"type":"number","format":"double","description":"AI's frequency penalty value for execution of this Generative Service."},"responseVariableName":{"type":"string","description":"Name of the variable in $hiddenContext this service will store it's result."},"usesBlacklist":{"type":"boolean","description":"Wether this execution should blacklist specific words."},"blacklistWords":{"type":"string","description":"A blacklist of comma-separated terms to be excluded from this service's generation."},"removed":{"type":"boolean","description":"Wether this service is logically excluded."},"createdAt":{"type":"string","format":"date-time","description":"An ISO formatted date of the creation of this Generative Service."},"updatedAt":{"type":"string","format":"date-time","description":"An ISO formatted date of the last update of this Generative Service."},"updatedBy":{"type":"string","description":"Uuid of the user that has last updated this Generative Service."},"createdBy":{"type":"string","description":"Uuid of the user that initially created this Generative Service."}}},"ParameterCapabilitiesDTO":{"type":"object","description":"Read-only parameter capabilities for the bot model","properties":{"family":{"type":"string","description":"Parameter family for the bot model","enum":["GPT_4","GPT_5"]},"model":{"type":"string","description":"Bot model name used to resolve capabilities"},"verbosity":{"$ref":"#/components/schemas/ParameterEnumCapabilityDTOVerbosity","description":"Verbosity allowed values and default; null for GPT-4"},"reasoningEffort":{"$ref":"#/components/schemas/ParameterEnumCapabilityDTOReasoningEffort","description":"Reasoning effort allowed values and default; null for GPT-4"}}},"ParameterEnumCapabilityDTOVerbosity":{"type":"object","description":"Allowed values and default for a model parameter enum","properties":{"allowed":{"type":"array","description":"Values allowed for the bot model version","items":{"type":"string","enum":["LOW","MEDIUM","HIGH"]}},"defaultValue":{"type":"string","description":"Default when the field is omitted on write","enum":["LOW","MEDIUM","HIGH"]}},"required":["allowed","defaultValue"]},"ParameterEnumCapabilityDTOReasoningEffort":{"type":"object","description":"Allowed values and default for a model parameter enum","properties":{"allowed":{"type":"array","description":"Values allowed for the bot model version","items":{"type":"string","description":"Reasoning effort for GPT-5 series. Allowed values depend on the bot model version.","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]}},"defaultValue":{"type":"string","description":"Default when the field is omitted on write","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]}},"required":["allowed","defaultValue"]},"FlowResponseDTO":{"type":"object","description":"Structure representing a flow's basic information.","properties":{"uuid":{"type":"string","description":"Uuid of the flow."},"name":{"type":"string","description":"Name of the flow"}}},"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}}
```

## GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service/{uuid}

> Retrieves info from a specific given Generative Service.

```json
{"openapi":"3.1.0","info":{"title":"eva-generative-service API Documentation","version":"4.9.0"},"tags":[{"name":"Generative Service Controller","description":"Management for creating, listing, finding, updating and deleting Generative Services"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service/{uuid}":{"get":{"tags":["Generative Service Controller"],"summary":"Retrieves info from a specific given Generative Service.","operationId":"findGenerativeService","parameters":[{"name":"orgUUID","in":"path","description":"A valid UUID of an organization","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid UUID of an environment","required":true,"schema":{"type":"string"}},{"name":"botUUID","in":"path","description":"The UUID of the bot to which the service belongs","required":true,"schema":{"type":"string"}},{"name":"uuid","in":"path","description":"The UUID of the generative service","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerativeServiceFlowsDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"GenerativeServiceFlowsDTO":{"type":"object","description":"A Structure holding a mapping of an Generative Service's information and all Flows associated to it.","properties":{"generativeService":{"$ref":"#/components/schemas/GenerativeServiceDTO","description":"All data regarding this Generative Service"},"flows":{"type":"array","description":"A list of Flows associated to this Generative Service","items":{"$ref":"#/components/schemas/FlowResponseDTO"}}}},"GenerativeServiceDTO":{"type":"object","description":"A Structure representing all data of a Generative Service.","properties":{"uuid":{"type":"string","description":"Uuid of this Generative Service."},"name":{"type":"string","description":"Name of this Generative Service."},"description":{"type":"string","description":"An optional description of this Generative Service."},"prompt":{"type":"string","description":"Actual prompt to be executed during AI generation when executing this service."},"model":{"type":"string","description":"AI Model to be used in this Generative Service."},"verbosity":{"type":"string","description":"Response verbosity for GPT-5 series models (LOW, MEDIUM, HIGH).","enum":["LOW","MEDIUM","HIGH"]},"reasoningEffort":{"type":"string","description":"Reasoning effort for GPT-5 series models (MINIMAL, LOW, MEDIUM, HIGH).","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]},"parameterCapabilities":{"$ref":"#/components/schemas/ParameterCapabilitiesDTO","description":"Read-only parameter capabilities for the persisted model (allowed values and defaults)","readOnly":true},"temperature":{"type":"number","format":"double","description":"AI's temperature value for execution of this Generative Service."},"maximumTokens":{"type":"integer","format":"int32","description":"Maximum tokens to be used during a single execution of this Generative Service."},"topP":{"type":"number","format":"double","description":"AI's topP value for execution of this Generative Service."},"presencePenalty":{"type":"number","format":"double","description":"AI's presence penalty value for execution of this Generative Service."},"frequencyPenalty":{"type":"number","format":"double","description":"AI's frequency penalty value for execution of this Generative Service."},"responseVariableName":{"type":"string","description":"Name of the variable in $hiddenContext this service will store it's result."},"usesBlacklist":{"type":"boolean","description":"Wether this execution should blacklist specific words."},"blacklistWords":{"type":"string","description":"A blacklist of comma-separated terms to be excluded from this service's generation."},"removed":{"type":"boolean","description":"Wether this service is logically excluded."},"createdAt":{"type":"string","format":"date-time","description":"An ISO formatted date of the creation of this Generative Service."},"updatedAt":{"type":"string","format":"date-time","description":"An ISO formatted date of the last update of this Generative Service."},"updatedBy":{"type":"string","description":"Uuid of the user that has last updated this Generative Service."},"createdBy":{"type":"string","description":"Uuid of the user that initially created this Generative Service."}}},"ParameterCapabilitiesDTO":{"type":"object","description":"Read-only parameter capabilities for the bot model","properties":{"family":{"type":"string","description":"Parameter family for the bot model","enum":["GPT_4","GPT_5"]},"model":{"type":"string","description":"Bot model name used to resolve capabilities"},"verbosity":{"$ref":"#/components/schemas/ParameterEnumCapabilityDTOVerbosity","description":"Verbosity allowed values and default; null for GPT-4"},"reasoningEffort":{"$ref":"#/components/schemas/ParameterEnumCapabilityDTOReasoningEffort","description":"Reasoning effort allowed values and default; null for GPT-4"}}},"ParameterEnumCapabilityDTOVerbosity":{"type":"object","description":"Allowed values and default for a model parameter enum","properties":{"allowed":{"type":"array","description":"Values allowed for the bot model version","items":{"type":"string","enum":["LOW","MEDIUM","HIGH"]}},"defaultValue":{"type":"string","description":"Default when the field is omitted on write","enum":["LOW","MEDIUM","HIGH"]}},"required":["allowed","defaultValue"]},"ParameterEnumCapabilityDTOReasoningEffort":{"type":"object","description":"Allowed values and default for a model parameter enum","properties":{"allowed":{"type":"array","description":"Values allowed for the bot model version","items":{"type":"string","description":"Reasoning effort for GPT-5 series. Allowed values depend on the bot model version.","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]}},"defaultValue":{"type":"string","description":"Default when the field is omitted on write","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]}},"required":["allowed","defaultValue"]},"FlowResponseDTO":{"type":"object","description":"Structure representing a flow's basic information.","properties":{"uuid":{"type":"string","description":"Uuid of the flow."},"name":{"type":"string","description":"Name of the flow"}}},"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}}
```

## PUT /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service/{uuid}

> Updates a Generative Service.

```json
{"openapi":"3.1.0","info":{"title":"eva-generative-service API Documentation","version":"4.9.0"},"tags":[{"name":"Generative Service Controller","description":"Management for creating, listing, finding, updating and deleting Generative Services"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service/{uuid}":{"put":{"tags":["Generative Service Controller"],"summary":"Updates a Generative Service.","operationId":"updateGenerativeService","parameters":[{"name":"orgUUID","in":"path","description":"A valid UUID of an organization","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid UUID of an environment","required":true,"schema":{"type":"string"}},{"name":"botUUID","in":"path","description":"The UUID of the bot whose entity is being updated","required":true,"schema":{"type":"string"}},{"name":"uuid","in":"path","description":"The Generative Service's UUID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerativeServiceRequestDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerativeServiceFlowsDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"GenerativeServiceRequestDTO":{"type":"object","description":"Contract required to request the creation of a Generative Service.","properties":{"name":{"type":"string","description":"Name of this Generative Service."},"description":{"type":"string","description":"An optional description of this Generative Service."},"prompt":{"type":"string","description":"Actual prompt to be executed during AI generation when executing this service."},"model":{"type":"string","description":"AI Model to be used in this Generative Service."},"verbosity":{"type":"string","description":"Response verbosity for GPT-5 series models (LOW, MEDIUM, HIGH).","enum":["LOW","MEDIUM","HIGH"]},"reasoningEffort":{"type":"string","description":"Reasoning effort for GPT-5 series models (MINIMAL, LOW, MEDIUM, HIGH).","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]},"temperature":{"type":"number","format":"double","description":"AI's temperature value for execution of this Generative Service."},"maximumTokens":{"type":"integer","format":"int32","description":"Maximum tokens to be used during a single execution of this Generative Service."},"topP":{"type":"number","format":"double","description":"AI's topP value for execution of this Generative Service."},"presencePenalty":{"type":"number","format":"double","description":"AI's presence penalty value for execution of this Generative Service."},"frequencyPenalty":{"type":"number","format":"double","description":"AI's frequency penalty value for execution of this Generative Service."},"responseVariableName":{"type":"string","description":"Name of the variable in $hiddenContext this service will store it's result."},"usesBlacklist":{"type":"boolean","description":"Whether this execution should blacklist specific words."},"blacklistWords":{"type":"string","description":"A blacklist of comma-separated terms to be excluded from this service's generation."}},"required":["name"]},"GenerativeServiceFlowsDTO":{"type":"object","description":"A Structure holding a mapping of an Generative Service's information and all Flows associated to it.","properties":{"generativeService":{"$ref":"#/components/schemas/GenerativeServiceDTO","description":"All data regarding this Generative Service"},"flows":{"type":"array","description":"A list of Flows associated to this Generative Service","items":{"$ref":"#/components/schemas/FlowResponseDTO"}}}},"GenerativeServiceDTO":{"type":"object","description":"A Structure representing all data of a Generative Service.","properties":{"uuid":{"type":"string","description":"Uuid of this Generative Service."},"name":{"type":"string","description":"Name of this Generative Service."},"description":{"type":"string","description":"An optional description of this Generative Service."},"prompt":{"type":"string","description":"Actual prompt to be executed during AI generation when executing this service."},"model":{"type":"string","description":"AI Model to be used in this Generative Service."},"verbosity":{"type":"string","description":"Response verbosity for GPT-5 series models (LOW, MEDIUM, HIGH).","enum":["LOW","MEDIUM","HIGH"]},"reasoningEffort":{"type":"string","description":"Reasoning effort for GPT-5 series models (MINIMAL, LOW, MEDIUM, HIGH).","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]},"parameterCapabilities":{"$ref":"#/components/schemas/ParameterCapabilitiesDTO","description":"Read-only parameter capabilities for the persisted model (allowed values and defaults)","readOnly":true},"temperature":{"type":"number","format":"double","description":"AI's temperature value for execution of this Generative Service."},"maximumTokens":{"type":"integer","format":"int32","description":"Maximum tokens to be used during a single execution of this Generative Service."},"topP":{"type":"number","format":"double","description":"AI's topP value for execution of this Generative Service."},"presencePenalty":{"type":"number","format":"double","description":"AI's presence penalty value for execution of this Generative Service."},"frequencyPenalty":{"type":"number","format":"double","description":"AI's frequency penalty value for execution of this Generative Service."},"responseVariableName":{"type":"string","description":"Name of the variable in $hiddenContext this service will store it's result."},"usesBlacklist":{"type":"boolean","description":"Wether this execution should blacklist specific words."},"blacklistWords":{"type":"string","description":"A blacklist of comma-separated terms to be excluded from this service's generation."},"removed":{"type":"boolean","description":"Wether this service is logically excluded."},"createdAt":{"type":"string","format":"date-time","description":"An ISO formatted date of the creation of this Generative Service."},"updatedAt":{"type":"string","format":"date-time","description":"An ISO formatted date of the last update of this Generative Service."},"updatedBy":{"type":"string","description":"Uuid of the user that has last updated this Generative Service."},"createdBy":{"type":"string","description":"Uuid of the user that initially created this Generative Service."}}},"ParameterCapabilitiesDTO":{"type":"object","description":"Read-only parameter capabilities for the bot model","properties":{"family":{"type":"string","description":"Parameter family for the bot model","enum":["GPT_4","GPT_5"]},"model":{"type":"string","description":"Bot model name used to resolve capabilities"},"verbosity":{"$ref":"#/components/schemas/ParameterEnumCapabilityDTOVerbosity","description":"Verbosity allowed values and default; null for GPT-4"},"reasoningEffort":{"$ref":"#/components/schemas/ParameterEnumCapabilityDTOReasoningEffort","description":"Reasoning effort allowed values and default; null for GPT-4"}}},"ParameterEnumCapabilityDTOVerbosity":{"type":"object","description":"Allowed values and default for a model parameter enum","properties":{"allowed":{"type":"array","description":"Values allowed for the bot model version","items":{"type":"string","enum":["LOW","MEDIUM","HIGH"]}},"defaultValue":{"type":"string","description":"Default when the field is omitted on write","enum":["LOW","MEDIUM","HIGH"]}},"required":["allowed","defaultValue"]},"ParameterEnumCapabilityDTOReasoningEffort":{"type":"object","description":"Allowed values and default for a model parameter enum","properties":{"allowed":{"type":"array","description":"Values allowed for the bot model version","items":{"type":"string","description":"Reasoning effort for GPT-5 series. Allowed values depend on the bot model version.","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]}},"defaultValue":{"type":"string","description":"Default when the field is omitted on write","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]}},"required":["allowed","defaultValue"]},"FlowResponseDTO":{"type":"object","description":"Structure representing a flow's basic information.","properties":{"uuid":{"type":"string","description":"Uuid of the flow."},"name":{"type":"string","description":"Name of the flow"}}},"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}}
```

## DELETE /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service/{uuid}

> Deletes a Generative Service. The Generative Service is disabled via the 'removed' parameter rather than deleted from the DB.

```json
{"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Generative Service Controller","description":"Management for creating, listing, finding, updating and deleting Generative Services"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service/{uuid}":{"delete":{"tags":["Generative Service Controller"],"summary":"Deletes a Generative Service. The Generative Service is disabled via the 'removed' parameter rather than deleted from the DB.","operationId":"deleteGenerativeService","parameters":[{"name":"orgUUID","in":"path","description":"A valid UUID of the organization","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid UUID of the environment","required":true,"schema":{"type":"string"}},{"name":"botUUID","in":"path","description":"A valid UUID of the bot","required":true,"schema":{"type":"string"}},{"name":"uuid","in":"path","description":"The UUID of the Generative Service","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok"},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}}
```

### Execution

The following section contains methods which are useable to test or simulate the cell's working.

## POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service/simulate

> Simulates a generative AI output.

```json
{"openapi":"3.1.0","info":{"title":"eva-generative-service API Documentation","version":"4.9.0"},"tags":[{"name":"Generative Service Controller","description":"Management for creating, listing, finding, updating and deleting Generative Services"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/generative-service/simulate":{"post":{"tags":["Generative Service Controller"],"summary":"Simulates a generative AI output.","operationId":"simulateContent","parameters":[{"name":"orgUUID","in":"path","description":"A valid uuid of organization","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid uuid of environment","required":true,"schema":{"type":"string"}},{"name":"botUUID","in":"path","description":"A valid uuid of bot","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerativeServiceRequestDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulatedResponseDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"GenerativeServiceRequestDTO":{"type":"object","description":"Contract required to request the creation of a Generative Service.","properties":{"name":{"type":"string","description":"Name of this Generative Service."},"description":{"type":"string","description":"An optional description of this Generative Service."},"prompt":{"type":"string","description":"Actual prompt to be executed during AI generation when executing this service."},"model":{"type":"string","description":"AI Model to be used in this Generative Service."},"verbosity":{"type":"string","description":"Response verbosity for GPT-5 series models (LOW, MEDIUM, HIGH).","enum":["LOW","MEDIUM","HIGH"]},"reasoningEffort":{"type":"string","description":"Reasoning effort for GPT-5 series models (MINIMAL, LOW, MEDIUM, HIGH).","enum":["NONE","MINIMAL","LOW","MEDIUM","HIGH","XHIGH"]},"temperature":{"type":"number","format":"double","description":"AI's temperature value for execution of this Generative Service."},"maximumTokens":{"type":"integer","format":"int32","description":"Maximum tokens to be used during a single execution of this Generative Service."},"topP":{"type":"number","format":"double","description":"AI's topP value for execution of this Generative Service."},"presencePenalty":{"type":"number","format":"double","description":"AI's presence penalty value for execution of this Generative Service."},"frequencyPenalty":{"type":"number","format":"double","description":"AI's frequency penalty value for execution of this Generative Service."},"responseVariableName":{"type":"string","description":"Name of the variable in $hiddenContext this service will store it's result."},"usesBlacklist":{"type":"boolean","description":"Whether this execution should blacklist specific words."},"blacklistWords":{"type":"string","description":"A blacklist of comma-separated terms to be excluded from this service's generation."}},"required":["name"]},"SimulatedResponseDTO":{"type":"object","properties":{"text":{"type":"string","description":"Text generated by prompt"},"usedTokens":{"type":"integer","format":"int32","description":"Consumed tokens for output"}},"required":["text","usedTokens"]},"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}}
```

## POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/answer/enhance

> Generates content for an answer, either enhancing previous texts or generating it on a whole.

```json
{"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Answer Controller","description":"Middleware endpoints used to perform Answer Assist modifications and generations."}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/answer/enhance":{"post":{"tags":["Answer Controller"],"summary":"Generates content for an answer, either enhancing previous texts or generating it on a whole.","operationId":"enhanceAnswer","parameters":[{"name":"orgUUID","in":"path","description":"A valid uuid of organization","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid uuid of environment","required":true,"schema":{"type":"string"}},{"name":"botUUID","in":"path","description":"A valid uuid of bot","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnswerAssistRequestDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnswerAssistResponseDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"AnswerAssistRequestDTO":{"type":"object","properties":{"enhancementType":{"type":"string","description":"Discerns which task will be performed to enhance this task.","enum":["GENERATE_CONTENT","IMPROVE_WRITING","SHORTEN","EXTEND","FIX_GRAMMAR","TONE_CHANGE"]},"inputText":{"type":"string","description":"Either the context, if enhancementType is GENERATE_CONTENT, or the previously existing answer otherwise."},"tone":{"type":"string","description":"Tone to be applied into the answer. Used only if enhancementType is 'TONE_CHANGE' or 'GENERATE_CONTENT'"},"language":{"type":"string","description":"Language of this bot."},"channelType":{"type":"integer","description":"It is the channel type from the answer","format":"int32"}},"description":"Structure with data for a Answer Assist enhancement request."},"AnswerAssistResponseDTO":{"required":["answer","enhancementType"],"type":"object","properties":{"answer":{"type":"string","description":"Answer generated by answer assist."},"enhancementType":{"type":"string","description":"Which Enhancement Type was used to generate this response.","enum":["GENERATE_CONTENT","IMPROVE_WRITING","SHORTEN","EXTEND","FIX_GRAMMAR","TONE_CHANGE"]}}},"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}}
```

### Auxiliary Methods

## GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/answer/availability

> Generates content for an answer, either enhancing previous texts or generating it on a whole.

```json
{"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Answer Controller","description":"Middleware endpoints used to perform Answer Assist modifications and generations."}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/answer/availability":{"get":{"tags":["Answer Controller"],"summary":"Generates content for an answer, either enhancing previous texts or generating it on a whole.","operationId":"getAvailability","parameters":[{"name":"orgUUID","in":"path","description":"A valid uuid of organization","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid uuid of environment","required":true,"schema":{"type":"string"}},{"name":"botUUID","in":"path","description":"A valid uuid of bot","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnswerAssistAvailabilityDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"AnswerAssistAvailabilityDTO":{"type":"object","properties":{"availableTones":{"type":"array","description":"Returns the currently available tone ENUM list.","items":{"type":"string","description":"Returns the currently available tone ENUM list.","enum":["ADVENTUROUS","CASUAL","FRIENDLY","PROFESSIONAL","HELPFUL","STRAIGHTFORWARD","WITTY"]}},"enabled":{"type":"boolean"}},"description":"Structure with data for a Answer Assist enhancement request."},"StandardError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"timestamp":{"type":"integer","format":"int64"},"errorCode":{"type":"string"},"errorType":{"type":"string","enum":["API_ERROR","API_INFO","USER_ERROR"]},"message":{"type":"string"},"path":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/FieldMessage"}}}},"FieldMessage":{"type":"object","properties":{"fieldName":{"type":"string"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs-conversational-ai.syntphony.com/api-docs/api-guidelines/management-api/instance-api/generative-service.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
