# Agent {% hint style="info" %} **API SUBPATH**: eva-generative-service {% endhint %} ## Supervisor ### Pagination and Listings ## GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/supervisors > Searches and paginates through supervisors ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Supervisor Controller","description":"Management for listing, finding, updating and managing Supervisors"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/supervisors":{"get":{"tags":["Supervisor Controller"],"summary":"Searches and paginates through supervisors","operationId":"page","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"}},{"name":"page","in":"query","description":"Current page, starting at 1","required":false,"schema":{"type":"integer","format":"int32","default":1}},{"name":"size","in":"query","description":"Size of the page","required":false,"schema":{"type":"integer","format":"int32","default":5}},{"name":"orderBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","default":"updatedAt"}},{"name":"direction","in":"query","description":"Sort direction (ASC or DESC)","required":false,"schema":{"type":"string","default":"DESC"}},{"name":"searchTerm","in":"query","description":"Optional search term to filter supervisors","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"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":{"Page":{"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":{"type":"object"}},"number":{"type":"integer","format":"int32"},"sort":{"$ref":"#/components/schemas/SortObject"},"first":{"type":"boolean"},"last":{"type":"boolean"},"empty":{"type":"boolean"}}},"PageableObject":{"type":"object","properties":{"unpaged":{"type":"boolean"},"pageNumber":{"type":"integer","format":"int32"},"paged":{"type":"boolean"},"pageSize":{"type":"integer","format":"int32"},"offset":{"type":"integer","format":"int64"},"sort":{"$ref":"#/components/schemas/SortObject"}}},"SortObject":{"type":"object","properties":{"unsorted":{"type":"boolean"},"sorted":{"type":"boolean"},"empty":{"type":"boolean"}}},"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 ## GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/supervisors/{supervisorUUID} > Retrieve a supervisor by its UUID ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Supervisor Controller","description":"Management for listing, finding, updating and managing Supervisors"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/supervisors/{supervisorUUID}":{"get":{"tags":["Supervisor Controller"],"summary":"Retrieve a supervisor by its UUID","operationId":"findByUUID","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"}},{"name":"supervisorUUID","in":"path","description":"The supervisor UUID to retrieve","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDTO"}}}},"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":{"application/json":{"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":{"AgentDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the agent"},"role":{"type":"string","description":"The role of the agent"},"flowUUID":{"type":"string","description":"UUID of the flow associated with the agent"},"goal":{"type":"string","description":"The goal of the agent"},"instructions":{"type":"string","description":"Detailed instructions for the agent"},"guardrails":{"type":"string","description":"Guardrails and limitations for the agent"},"persona":{"$ref":"#/components/schemas/BasicPersonaDTO"},"inheritFromSupervisor":{"type":"boolean","description":"Whether the agent inherits configurations from supervisor"},"constraints":{"type":"array","description":"List of constraints/rules for the agent","items":{"$ref":"#/components/schemas/RuleDTO"}},"tags":{"type":"array","description":"List of tags associated with the agent","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameters":{"$ref":"#/components/schemas/ParametersDTO"},"functions":{"type":"array","description":"List of functions available to the agent","items":{"$ref":"#/components/schemas/AgentFunctionDTO"}},"knowledge":{"type":"array","description":"List of knowledge collections for the agent","items":{"$ref":"#/components/schemas/CollectionDTO"}},"heirs":{"type":"array","description":"List of heir agents","items":{"$ref":"#/components/schemas/BasicAgentDTO"}}},"description":"Data Transfer Object representing an Agent with all its configurations and relationships"},"BasicPersonaDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the persona"},"name":{"type":"string","description":"Name of the persona"},"image":{"type":"string","description":"Image URL of the persona"},"backstory":{"type":"string","description":"Backstory of the persona"},"personality":{"type":"string","description":"Personality traits of the persona"},"communicationStyle":{"type":"string","description":"Different styles of communication.","enum":["POLITE_AND_PERSUASIVE","WITTY_AND_CASUAL","EMPATHETIC_AND_HELPFUL","CONCISE_AND_PROFESSIONAL","FRIENDLY_AND_APPROACHABLE"]}},"description":"Basic Persona Data Transfer Object"},"RuleDTO":{"required":["value"],"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the rule"},"value":{"type":"string","description":"Value associated with the rule"}},"description":"Data Transfer Object for Rule"},"TagSimpleDTO":{"required":["name"],"type":"object","properties":{"uuid":{"type":"string","description":"Uuid of the tag, if existing. Not required, but will speed up the creation if present."},"name":{"type":"string","description":"Name of the tag. Expected to be in a '#term' format, hash included."}},"description":"Simplified structure representing a tag only by name and uuid"},"ParametersDTO":{"required":["frequencyPenalty","presencePenalty","requestTimeout","temperature","topP"],"type":"object","properties":{"maximumTokens":{"type":"integer","description":"Maximum number of tokens allowed in the response","format":"int32"},"requestTimeout":{"type":"integer","description":"Timeout for the request in milliseconds","format":"int64"},"temperature":{"type":"number","description":"Temperature parameter for controlling randomness in responses","format":"double"},"topP":{"type":"number","description":"Top P parameter for nucleus sampling","format":"double"},"presencePenalty":{"type":"number","description":"Penalty for presence of tokens in the response","format":"double"},"frequencyPenalty":{"type":"number","description":"Penalty for frequency of tokens in the response","format":"double"}},"description":"Data Transfer Object for configuration parameters in AI/ML models"},"AgentFunctionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the AgentFunction"},"name":{"type":"string","description":"Name of the AgentFunction"}},"description":"Data Transfer Object for AgentFunction entity"},"CollectionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the collection."},"name":{"type":"string","description":"Name of the collection."},"description":{"type":"string","description":"Description of the collection."},"documentCount":{"type":"integer","description":"Number of documents in the collection.","format":"int32"},"searchType":{"$ref":"#/components/schemas/CollectionSearchTypeDTO"},"previousUserInput":{"type":"integer","description":"Previous user input for the collection.","format":"int32"},"threshold":{"type":"number","description":"Threshold value for collection operations.","format":"double"},"topK":{"type":"integer","description":"Top K results configuration for the collection.","format":"int32"}},"description":"Data Transfer Object for a collection."},"CollectionSearchTypeDTO":{"type":"object","properties":{"type":{"type":"string","description":"The type of search"},"semanticWeight":{"type":"integer","description":"The semantic weight of the search type","format":"int32"},"fullTextWeight":{"type":"integer","description":"The full text weight of the search type","format":"int32"}},"description":"DTO for representing search type details"},"BasicAgentDTO":{"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"}},"description":"Data Transfer Object for Basic Agent Information"},"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}/supervisors/{supervisorUUID} > Update an existing supervisor by its UUID ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Supervisor Controller","description":"Management for listing, finding, updating and managing Supervisors"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/supervisors/{supervisorUUID}":{"put":{"tags":["Supervisor Controller"],"summary":"Update an existing supervisor by its UUID","operationId":"update","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"}},{"name":"supervisorUUID","in":"path","description":"The supervisor UUID to update","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupervisorDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDTO"}}}},"400":{"description":"Bad Request","content":{"application/json":{"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":{"application/json":{"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":{"SupervisorDTO":{"required":["persona"],"type":"object","properties":{"instructions":{"type":"string","description":"Instructions for the supervisor"},"guardrails":{"type":"string","description":"Guardrails and limitations for the supervisor"},"persona":{"$ref":"#/components/schemas/ExternalResourceDTO"},"constraints":{"type":"array","description":"List of constraints/rules for the supervisor","items":{"$ref":"#/components/schemas/RuleDTO"}},"tags":{"type":"array","description":"List of tags associated with the supervisor","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameters":{"$ref":"#/components/schemas/ParametersDTO"}},"description":"Data Transfer Object representing the configuration and attributes for a supervisor"},"ExternalResourceDTO":{"required":["uuid"],"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the external resource"}},"description":"Data Transfer Object representing an external resource identified by UUID"},"RuleDTO":{"required":["value"],"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the rule"},"value":{"type":"string","description":"Value associated with the rule"}},"description":"Data Transfer Object for Rule"},"TagSimpleDTO":{"required":["name"],"type":"object","properties":{"uuid":{"type":"string","description":"Uuid of the tag, if existing. Not required, but will speed up the creation if present."},"name":{"type":"string","description":"Name of the tag. Expected to be in a '#term' format, hash included."}},"description":"Simplified structure representing a tag only by name and uuid"},"ParametersDTO":{"required":["frequencyPenalty","presencePenalty","requestTimeout","temperature","topP"],"type":"object","properties":{"maximumTokens":{"type":"integer","description":"Maximum number of tokens allowed in the response","format":"int32"},"requestTimeout":{"type":"integer","description":"Timeout for the request in milliseconds","format":"int64"},"temperature":{"type":"number","description":"Temperature parameter for controlling randomness in responses","format":"double"},"topP":{"type":"number","description":"Top P parameter for nucleus sampling","format":"double"},"presencePenalty":{"type":"number","description":"Penalty for presence of tokens in the response","format":"double"},"frequencyPenalty":{"type":"number","description":"Penalty for frequency of tokens in the response","format":"double"}},"description":"Data Transfer Object for configuration parameters in AI/ML models"},"AgentDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the agent"},"role":{"type":"string","description":"The role of the agent"},"flowUUID":{"type":"string","description":"UUID of the flow associated with the agent"},"goal":{"type":"string","description":"The goal of the agent"},"instructions":{"type":"string","description":"Detailed instructions for the agent"},"guardrails":{"type":"string","description":"Guardrails and limitations for the agent"},"persona":{"$ref":"#/components/schemas/BasicPersonaDTO"},"inheritFromSupervisor":{"type":"boolean","description":"Whether the agent inherits configurations from supervisor"},"constraints":{"type":"array","description":"List of constraints/rules for the agent","items":{"$ref":"#/components/schemas/RuleDTO"}},"tags":{"type":"array","description":"List of tags associated with the agent","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameters":{"$ref":"#/components/schemas/ParametersDTO"},"functions":{"type":"array","description":"List of functions available to the agent","items":{"$ref":"#/components/schemas/AgentFunctionDTO"}},"knowledge":{"type":"array","description":"List of knowledge collections for the agent","items":{"$ref":"#/components/schemas/CollectionDTO"}},"heirs":{"type":"array","description":"List of heir agents","items":{"$ref":"#/components/schemas/BasicAgentDTO"}}},"description":"Data Transfer Object representing an Agent with all its configurations and relationships"},"BasicPersonaDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the persona"},"name":{"type":"string","description":"Name of the persona"},"image":{"type":"string","description":"Image URL of the persona"},"backstory":{"type":"string","description":"Backstory of the persona"},"personality":{"type":"string","description":"Personality traits of the persona"},"communicationStyle":{"type":"string","description":"Different styles of communication.","enum":["POLITE_AND_PERSUASIVE","WITTY_AND_CASUAL","EMPATHETIC_AND_HELPFUL","CONCISE_AND_PROFESSIONAL","FRIENDLY_AND_APPROACHABLE"]}},"description":"Basic Persona Data Transfer Object"},"AgentFunctionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the AgentFunction"},"name":{"type":"string","description":"Name of the AgentFunction"}},"description":"Data Transfer Object for AgentFunction entity"},"CollectionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the collection."},"name":{"type":"string","description":"Name of the collection."},"description":{"type":"string","description":"Description of the collection."},"documentCount":{"type":"integer","description":"Number of documents in the collection.","format":"int32"},"searchType":{"$ref":"#/components/schemas/CollectionSearchTypeDTO"},"previousUserInput":{"type":"integer","description":"Previous user input for the collection.","format":"int32"},"threshold":{"type":"number","description":"Threshold value for collection operations.","format":"double"},"topK":{"type":"integer","description":"Top K results configuration for the collection.","format":"int32"}},"description":"Data Transfer Object for a collection."},"CollectionSearchTypeDTO":{"type":"object","properties":{"type":{"type":"string","description":"The type of search"},"semanticWeight":{"type":"integer","description":"The semantic weight of the search type","format":"int32"},"fullTextWeight":{"type":"integer","description":"The full text weight of the search type","format":"int32"}},"description":"DTO for representing search type details"},"BasicAgentDTO":{"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"}},"description":"Data Transfer Object for Basic Agent Information"},"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}/supervisors/default > Retrieve the default supervisor ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Supervisor Controller","description":"Management for listing, finding, updating and managing Supervisors"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/supervisors/default":{"get":{"tags":["Supervisor Controller"],"summary":"Retrieve the default supervisor","operationId":"defaultSupervisor","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/AgentDTO"}}}},"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":{"AgentDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the agent"},"role":{"type":"string","description":"The role of the agent"},"flowUUID":{"type":"string","description":"UUID of the flow associated with the agent"},"goal":{"type":"string","description":"The goal of the agent"},"instructions":{"type":"string","description":"Detailed instructions for the agent"},"guardrails":{"type":"string","description":"Guardrails and limitations for the agent"},"persona":{"$ref":"#/components/schemas/BasicPersonaDTO"},"inheritFromSupervisor":{"type":"boolean","description":"Whether the agent inherits configurations from supervisor"},"constraints":{"type":"array","description":"List of constraints/rules for the agent","items":{"$ref":"#/components/schemas/RuleDTO"}},"tags":{"type":"array","description":"List of tags associated with the agent","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameters":{"$ref":"#/components/schemas/ParametersDTO"},"functions":{"type":"array","description":"List of functions available to the agent","items":{"$ref":"#/components/schemas/AgentFunctionDTO"}},"knowledge":{"type":"array","description":"List of knowledge collections for the agent","items":{"$ref":"#/components/schemas/CollectionDTO"}},"heirs":{"type":"array","description":"List of heir agents","items":{"$ref":"#/components/schemas/BasicAgentDTO"}}},"description":"Data Transfer Object representing an Agent with all its configurations and relationships"},"BasicPersonaDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the persona"},"name":{"type":"string","description":"Name of the persona"},"image":{"type":"string","description":"Image URL of the persona"},"backstory":{"type":"string","description":"Backstory of the persona"},"personality":{"type":"string","description":"Personality traits of the persona"},"communicationStyle":{"type":"string","description":"Different styles of communication.","enum":["POLITE_AND_PERSUASIVE","WITTY_AND_CASUAL","EMPATHETIC_AND_HELPFUL","CONCISE_AND_PROFESSIONAL","FRIENDLY_AND_APPROACHABLE"]}},"description":"Basic Persona Data Transfer Object"},"RuleDTO":{"required":["value"],"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the rule"},"value":{"type":"string","description":"Value associated with the rule"}},"description":"Data Transfer Object for Rule"},"TagSimpleDTO":{"required":["name"],"type":"object","properties":{"uuid":{"type":"string","description":"Uuid of the tag, if existing. Not required, but will speed up the creation if present."},"name":{"type":"string","description":"Name of the tag. Expected to be in a '#term' format, hash included."}},"description":"Simplified structure representing a tag only by name and uuid"},"ParametersDTO":{"required":["frequencyPenalty","presencePenalty","requestTimeout","temperature","topP"],"type":"object","properties":{"maximumTokens":{"type":"integer","description":"Maximum number of tokens allowed in the response","format":"int32"},"requestTimeout":{"type":"integer","description":"Timeout for the request in milliseconds","format":"int64"},"temperature":{"type":"number","description":"Temperature parameter for controlling randomness in responses","format":"double"},"topP":{"type":"number","description":"Top P parameter for nucleus sampling","format":"double"},"presencePenalty":{"type":"number","description":"Penalty for presence of tokens in the response","format":"double"},"frequencyPenalty":{"type":"number","description":"Penalty for frequency of tokens in the response","format":"double"}},"description":"Data Transfer Object for configuration parameters in AI/ML models"},"AgentFunctionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the AgentFunction"},"name":{"type":"string","description":"Name of the AgentFunction"}},"description":"Data Transfer Object for AgentFunction entity"},"CollectionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the collection."},"name":{"type":"string","description":"Name of the collection."},"description":{"type":"string","description":"Description of the collection."},"documentCount":{"type":"integer","description":"Number of documents in the collection.","format":"int32"},"searchType":{"$ref":"#/components/schemas/CollectionSearchTypeDTO"},"previousUserInput":{"type":"integer","description":"Previous user input for the collection.","format":"int32"},"threshold":{"type":"number","description":"Threshold value for collection operations.","format":"double"},"topK":{"type":"integer","description":"Top K results configuration for the collection.","format":"int32"}},"description":"Data Transfer Object for a collection."},"CollectionSearchTypeDTO":{"type":"object","properties":{"type":{"type":"string","description":"The type of search"},"semanticWeight":{"type":"integer","description":"The semantic weight of the search type","format":"int32"},"fullTextWeight":{"type":"integer","description":"The full text weight of the search type","format":"int32"}},"description":"DTO for representing search type details"},"BasicAgentDTO":{"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"}},"description":"Data Transfer Object for Basic Agent Information"},"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 ### Pagination and Listings ## GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/agents > Searches and paginates through agents ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Agent Controller","description":"Management for creating, listing, finding, updating and deleting Agents"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/agents":{"get":{"tags":["Agent Controller"],"summary":"Searches and paginates through agents","operationId":"page_3","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"}},{"name":"page","in":"query","description":"Current page, starting at 1","required":false,"schema":{"type":"integer","format":"int32","default":1}},{"name":"size","in":"query","description":"Size of the page","required":false,"schema":{"type":"integer","format":"int32","default":5}},{"name":"orderBy","in":"query","description":"The field to order results by","required":false,"schema":{"type":"string","default":"updatedAt"}},{"name":"direction","in":"query","description":"The sort direction (ASC or DESC)","required":false,"schema":{"type":"string","default":"DESC"}},{"name":"searchTerm","in":"query","description":"Optional search term to filter results","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"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":{"Page":{"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":{"type":"object"}},"number":{"type":"integer","format":"int32"},"sort":{"$ref":"#/components/schemas/SortObject"},"first":{"type":"boolean"},"last":{"type":"boolean"},"empty":{"type":"boolean"}}},"PageableObject":{"type":"object","properties":{"unpaged":{"type":"boolean"},"pageNumber":{"type":"integer","format":"int32"},"paged":{"type":"boolean"},"pageSize":{"type":"integer","format":"int32"},"offset":{"type":"integer","format":"int64"},"sort":{"$ref":"#/components/schemas/SortObject"}}},"SortObject":{"type":"object","properties":{"unsorted":{"type":"boolean"},"sorted":{"type":"boolean"},"empty":{"type":"boolean"}}},"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}/agents/quicksearch > Perform a quick search for agent names ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Agent Controller","description":"Management for creating, listing, finding, updating and deleting Agents"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/agents/quicksearch":{"get":{"tags":["Agent Controller"],"summary":"Perform a quick search for agent names","operationId":"quicksearch_2","parameters":[{"name":"x-request-id","in":"header","required":false,"schema":{"type":"string"}},{"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"}},{"name":"name","in":"query","description":"The name of the agent for quick search","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"The maximum number of results to return","required":false,"schema":{"type":"integer","format":"int32","default":6}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"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":{"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":{"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}/agents > Create a new agent ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Agent Controller","description":"Management for creating, listing, finding, updating and deleting Agents"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/agents":{"post":{"tags":["Agent Controller"],"summary":"Create a new agent","operationId":"create_2","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/CreateAgentDTO"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDTO"}}}},"400":{"description":"Bad Request","content":{"application/json":{"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":{"CreateAgentDTO":{"required":["goal","inheritFromSupervisor","persona","role"],"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"},"goal":{"type":"string","description":"The goal of the agent"},"instructions":{"type":"string","description":"Detailed instructions for the agent"},"guardrails":{"type":"string","description":"Guardrails and limitations for the agent"},"persona":{"$ref":"#/components/schemas/ExternalResourceDTO"},"constraints":{"type":"array","description":"List of constraints/rules for the agent","items":{"$ref":"#/components/schemas/CreateRuleDTO"}},"tags":{"type":"array","description":"List of tags associated with the agent","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameters":{"$ref":"#/components/schemas/ParametersDTO"},"inheritFromSupervisor":{"type":"boolean","description":"Whether the agent should inherit configurations from supervisor"},"functions":{"type":"array","description":"List of functions available to the agent","items":{"$ref":"#/components/schemas/ExternalResourceDTO"}},"knowledge":{"type":"array","description":"List of knowledge collections for the agent","items":{"$ref":"#/components/schemas/ExternalResourceDTO"}}},"description":"Data Transfer Object representing the parameters required to create an agent"},"ExternalResourceDTO":{"required":["uuid"],"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the external resource"}},"description":"Data Transfer Object representing an external resource identified by UUID"},"CreateRuleDTO":{"required":["value"],"type":"object","properties":{"value":{"type":"string","description":"The rule value, which is required and cannot be blank."}},"description":"Data Transfer Object for creating a rule associated with an agentic function parameter."},"TagSimpleDTO":{"required":["name"],"type":"object","properties":{"uuid":{"type":"string","description":"Uuid of the tag, if existing. Not required, but will speed up the creation if present."},"name":{"type":"string","description":"Name of the tag. Expected to be in a '#term' format, hash included."}},"description":"Simplified structure representing a tag only by name and uuid"},"ParametersDTO":{"required":["frequencyPenalty","presencePenalty","requestTimeout","temperature","topP"],"type":"object","properties":{"maximumTokens":{"type":"integer","description":"Maximum number of tokens allowed in the response","format":"int32"},"requestTimeout":{"type":"integer","description":"Timeout for the request in milliseconds","format":"int64"},"temperature":{"type":"number","description":"Temperature parameter for controlling randomness in responses","format":"double"},"topP":{"type":"number","description":"Top P parameter for nucleus sampling","format":"double"},"presencePenalty":{"type":"number","description":"Penalty for presence of tokens in the response","format":"double"},"frequencyPenalty":{"type":"number","description":"Penalty for frequency of tokens in the response","format":"double"}},"description":"Data Transfer Object for configuration parameters in AI/ML models"},"AgentDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the agent"},"role":{"type":"string","description":"The role of the agent"},"flowUUID":{"type":"string","description":"UUID of the flow associated with the agent"},"goal":{"type":"string","description":"The goal of the agent"},"instructions":{"type":"string","description":"Detailed instructions for the agent"},"guardrails":{"type":"string","description":"Guardrails and limitations for the agent"},"persona":{"$ref":"#/components/schemas/BasicPersonaDTO"},"inheritFromSupervisor":{"type":"boolean","description":"Whether the agent inherits configurations from supervisor"},"constraints":{"type":"array","description":"List of constraints/rules for the agent","items":{"$ref":"#/components/schemas/RuleDTO"}},"tags":{"type":"array","description":"List of tags associated with the agent","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameters":{"$ref":"#/components/schemas/ParametersDTO"},"functions":{"type":"array","description":"List of functions available to the agent","items":{"$ref":"#/components/schemas/AgentFunctionDTO"}},"knowledge":{"type":"array","description":"List of knowledge collections for the agent","items":{"$ref":"#/components/schemas/CollectionDTO"}},"heirs":{"type":"array","description":"List of heir agents","items":{"$ref":"#/components/schemas/BasicAgentDTO"}}},"description":"Data Transfer Object representing an Agent with all its configurations and relationships"},"BasicPersonaDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the persona"},"name":{"type":"string","description":"Name of the persona"},"image":{"type":"string","description":"Image URL of the persona"},"backstory":{"type":"string","description":"Backstory of the persona"},"personality":{"type":"string","description":"Personality traits of the persona"},"communicationStyle":{"type":"string","description":"Different styles of communication.","enum":["POLITE_AND_PERSUASIVE","WITTY_AND_CASUAL","EMPATHETIC_AND_HELPFUL","CONCISE_AND_PROFESSIONAL","FRIENDLY_AND_APPROACHABLE"]}},"description":"Basic Persona Data Transfer Object"},"RuleDTO":{"required":["value"],"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the rule"},"value":{"type":"string","description":"Value associated with the rule"}},"description":"Data Transfer Object for Rule"},"AgentFunctionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the AgentFunction"},"name":{"type":"string","description":"Name of the AgentFunction"}},"description":"Data Transfer Object for AgentFunction entity"},"CollectionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the collection."},"name":{"type":"string","description":"Name of the collection."},"description":{"type":"string","description":"Description of the collection."},"documentCount":{"type":"integer","description":"Number of documents in the collection.","format":"int32"},"searchType":{"$ref":"#/components/schemas/CollectionSearchTypeDTO"},"previousUserInput":{"type":"integer","description":"Previous user input for the collection.","format":"int32"},"threshold":{"type":"number","description":"Threshold value for collection operations.","format":"double"},"topK":{"type":"integer","description":"Top K results configuration for the collection.","format":"int32"}},"description":"Data Transfer Object for a collection."},"CollectionSearchTypeDTO":{"type":"object","properties":{"type":{"type":"string","description":"The type of search"},"semanticWeight":{"type":"integer","description":"The semantic weight of the search type","format":"int32"},"fullTextWeight":{"type":"integer","description":"The full text weight of the search type","format":"int32"}},"description":"DTO for representing search type details"},"BasicAgentDTO":{"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"}},"description":"Data Transfer Object for Basic Agent Information"},"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}/agents/{agentUUID} > Find an agent by its UUID ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Agent Controller","description":"Management for creating, listing, finding, updating and deleting Agents"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/agents/{agentUUID}":{"get":{"tags":["Agent Controller"],"summary":"Find an agent by its UUID","operationId":"findByUUID_3","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"}},{"name":"agentUUID","in":"path","description":"The specific agent UUID to retrieve","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDTO"}}}},"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":{"application/json":{"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":{"AgentDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the agent"},"role":{"type":"string","description":"The role of the agent"},"flowUUID":{"type":"string","description":"UUID of the flow associated with the agent"},"goal":{"type":"string","description":"The goal of the agent"},"instructions":{"type":"string","description":"Detailed instructions for the agent"},"guardrails":{"type":"string","description":"Guardrails and limitations for the agent"},"persona":{"$ref":"#/components/schemas/BasicPersonaDTO"},"inheritFromSupervisor":{"type":"boolean","description":"Whether the agent inherits configurations from supervisor"},"constraints":{"type":"array","description":"List of constraints/rules for the agent","items":{"$ref":"#/components/schemas/RuleDTO"}},"tags":{"type":"array","description":"List of tags associated with the agent","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameters":{"$ref":"#/components/schemas/ParametersDTO"},"functions":{"type":"array","description":"List of functions available to the agent","items":{"$ref":"#/components/schemas/AgentFunctionDTO"}},"knowledge":{"type":"array","description":"List of knowledge collections for the agent","items":{"$ref":"#/components/schemas/CollectionDTO"}},"heirs":{"type":"array","description":"List of heir agents","items":{"$ref":"#/components/schemas/BasicAgentDTO"}}},"description":"Data Transfer Object representing an Agent with all its configurations and relationships"},"BasicPersonaDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the persona"},"name":{"type":"string","description":"Name of the persona"},"image":{"type":"string","description":"Image URL of the persona"},"backstory":{"type":"string","description":"Backstory of the persona"},"personality":{"type":"string","description":"Personality traits of the persona"},"communicationStyle":{"type":"string","description":"Different styles of communication.","enum":["POLITE_AND_PERSUASIVE","WITTY_AND_CASUAL","EMPATHETIC_AND_HELPFUL","CONCISE_AND_PROFESSIONAL","FRIENDLY_AND_APPROACHABLE"]}},"description":"Basic Persona Data Transfer Object"},"RuleDTO":{"required":["value"],"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the rule"},"value":{"type":"string","description":"Value associated with the rule"}},"description":"Data Transfer Object for Rule"},"TagSimpleDTO":{"required":["name"],"type":"object","properties":{"uuid":{"type":"string","description":"Uuid of the tag, if existing. Not required, but will speed up the creation if present."},"name":{"type":"string","description":"Name of the tag. Expected to be in a '#term' format, hash included."}},"description":"Simplified structure representing a tag only by name and uuid"},"ParametersDTO":{"required":["frequencyPenalty","presencePenalty","requestTimeout","temperature","topP"],"type":"object","properties":{"maximumTokens":{"type":"integer","description":"Maximum number of tokens allowed in the response","format":"int32"},"requestTimeout":{"type":"integer","description":"Timeout for the request in milliseconds","format":"int64"},"temperature":{"type":"number","description":"Temperature parameter for controlling randomness in responses","format":"double"},"topP":{"type":"number","description":"Top P parameter for nucleus sampling","format":"double"},"presencePenalty":{"type":"number","description":"Penalty for presence of tokens in the response","format":"double"},"frequencyPenalty":{"type":"number","description":"Penalty for frequency of tokens in the response","format":"double"}},"description":"Data Transfer Object for configuration parameters in AI/ML models"},"AgentFunctionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the AgentFunction"},"name":{"type":"string","description":"Name of the AgentFunction"}},"description":"Data Transfer Object for AgentFunction entity"},"CollectionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the collection."},"name":{"type":"string","description":"Name of the collection."},"description":{"type":"string","description":"Description of the collection."},"documentCount":{"type":"integer","description":"Number of documents in the collection.","format":"int32"},"searchType":{"$ref":"#/components/schemas/CollectionSearchTypeDTO"},"previousUserInput":{"type":"integer","description":"Previous user input for the collection.","format":"int32"},"threshold":{"type":"number","description":"Threshold value for collection operations.","format":"double"},"topK":{"type":"integer","description":"Top K results configuration for the collection.","format":"int32"}},"description":"Data Transfer Object for a collection."},"CollectionSearchTypeDTO":{"type":"object","properties":{"type":{"type":"string","description":"The type of search"},"semanticWeight":{"type":"integer","description":"The semantic weight of the search type","format":"int32"},"fullTextWeight":{"type":"integer","description":"The full text weight of the search type","format":"int32"}},"description":"DTO for representing search type details"},"BasicAgentDTO":{"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"}},"description":"Data Transfer Object for Basic Agent Information"},"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}/agents/{agentUUID} > Update an existing agent by its UUID ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Agent Controller","description":"Management for creating, listing, finding, updating and deleting Agents"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/agents/{agentUUID}":{"put":{"tags":["Agent Controller"],"summary":"Update an existing agent by its UUID","operationId":"update_3","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"}},{"name":"agentUUID","in":"path","description":"The specific agent UUID to update","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDTO"}}}},"400":{"description":"Bad Request","content":{"application/json":{"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":{"application/json":{"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":{"UpdateAgentDTO":{"required":["goal","inheritFromSupervisor","persona","role"],"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"},"goal":{"type":"string","description":"The goal of the agent"},"instructions":{"type":"string","description":"Detailed instructions for the agent"},"guardrails":{"type":"string","description":"Guardrails and limitations for the agent"},"persona":{"$ref":"#/components/schemas/ExternalResourceDTO"},"constraints":{"type":"array","description":"List of constraints/rules for the agent","items":{"$ref":"#/components/schemas/RuleDTO"}},"tags":{"type":"array","description":"List of tags associated with the agent","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameters":{"$ref":"#/components/schemas/ParametersDTO"},"inheritFromSupervisor":{"type":"boolean","description":"Whether the agent should inherit configurations from supervisor"},"functions":{"type":"array","description":"List of functions available to the agent","items":{"$ref":"#/components/schemas/ExternalResourceDTO"}},"knowledge":{"type":"array","description":"List of knowledge collections for the agent","items":{"$ref":"#/components/schemas/ExternalResourceDTO"}}},"description":"Data Transfer Object representing the necessary fields for updating an agent"},"ExternalResourceDTO":{"required":["uuid"],"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the external resource"}},"description":"Data Transfer Object representing an external resource identified by UUID"},"RuleDTO":{"required":["value"],"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the rule"},"value":{"type":"string","description":"Value associated with the rule"}},"description":"Data Transfer Object for Rule"},"TagSimpleDTO":{"required":["name"],"type":"object","properties":{"uuid":{"type":"string","description":"Uuid of the tag, if existing. Not required, but will speed up the creation if present."},"name":{"type":"string","description":"Name of the tag. Expected to be in a '#term' format, hash included."}},"description":"Simplified structure representing a tag only by name and uuid"},"ParametersDTO":{"required":["frequencyPenalty","presencePenalty","requestTimeout","temperature","topP"],"type":"object","properties":{"maximumTokens":{"type":"integer","description":"Maximum number of tokens allowed in the response","format":"int32"},"requestTimeout":{"type":"integer","description":"Timeout for the request in milliseconds","format":"int64"},"temperature":{"type":"number","description":"Temperature parameter for controlling randomness in responses","format":"double"},"topP":{"type":"number","description":"Top P parameter for nucleus sampling","format":"double"},"presencePenalty":{"type":"number","description":"Penalty for presence of tokens in the response","format":"double"},"frequencyPenalty":{"type":"number","description":"Penalty for frequency of tokens in the response","format":"double"}},"description":"Data Transfer Object for configuration parameters in AI/ML models"},"AgentDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the agent"},"role":{"type":"string","description":"The role of the agent"},"flowUUID":{"type":"string","description":"UUID of the flow associated with the agent"},"goal":{"type":"string","description":"The goal of the agent"},"instructions":{"type":"string","description":"Detailed instructions for the agent"},"guardrails":{"type":"string","description":"Guardrails and limitations for the agent"},"persona":{"$ref":"#/components/schemas/BasicPersonaDTO"},"inheritFromSupervisor":{"type":"boolean","description":"Whether the agent inherits configurations from supervisor"},"constraints":{"type":"array","description":"List of constraints/rules for the agent","items":{"$ref":"#/components/schemas/RuleDTO"}},"tags":{"type":"array","description":"List of tags associated with the agent","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameters":{"$ref":"#/components/schemas/ParametersDTO"},"functions":{"type":"array","description":"List of functions available to the agent","items":{"$ref":"#/components/schemas/AgentFunctionDTO"}},"knowledge":{"type":"array","description":"List of knowledge collections for the agent","items":{"$ref":"#/components/schemas/CollectionDTO"}},"heirs":{"type":"array","description":"List of heir agents","items":{"$ref":"#/components/schemas/BasicAgentDTO"}}},"description":"Data Transfer Object representing an Agent with all its configurations and relationships"},"BasicPersonaDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the persona"},"name":{"type":"string","description":"Name of the persona"},"image":{"type":"string","description":"Image URL of the persona"},"backstory":{"type":"string","description":"Backstory of the persona"},"personality":{"type":"string","description":"Personality traits of the persona"},"communicationStyle":{"type":"string","description":"Different styles of communication.","enum":["POLITE_AND_PERSUASIVE","WITTY_AND_CASUAL","EMPATHETIC_AND_HELPFUL","CONCISE_AND_PROFESSIONAL","FRIENDLY_AND_APPROACHABLE"]}},"description":"Basic Persona Data Transfer Object"},"AgentFunctionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the AgentFunction"},"name":{"type":"string","description":"Name of the AgentFunction"}},"description":"Data Transfer Object for AgentFunction entity"},"CollectionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the collection."},"name":{"type":"string","description":"Name of the collection."},"description":{"type":"string","description":"Description of the collection."},"documentCount":{"type":"integer","description":"Number of documents in the collection.","format":"int32"},"searchType":{"$ref":"#/components/schemas/CollectionSearchTypeDTO"},"previousUserInput":{"type":"integer","description":"Previous user input for the collection.","format":"int32"},"threshold":{"type":"number","description":"Threshold value for collection operations.","format":"double"},"topK":{"type":"integer","description":"Top K results configuration for the collection.","format":"int32"}},"description":"Data Transfer Object for a collection."},"CollectionSearchTypeDTO":{"type":"object","properties":{"type":{"type":"string","description":"The type of search"},"semanticWeight":{"type":"integer","description":"The semantic weight of the search type","format":"int32"},"fullTextWeight":{"type":"integer","description":"The full text weight of the search type","format":"int32"}},"description":"DTO for representing search type details"},"BasicAgentDTO":{"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"}},"description":"Data Transfer Object for Basic Agent Information"},"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}/agents/{agentUUID} > Delete an agent by its UUID ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Agent Controller","description":"Management for creating, listing, finding, updating and deleting Agents"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/agents/{agentUUID}":{"delete":{"tags":["Agent Controller"],"summary":"Delete an agent by its UUID","operationId":"delete_2","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"}},{"name":"agentUUID","in":"path","description":"The specific agent UUID to delete","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSummaryDTO"}}}},"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":{"application/json":{"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":{"DeleteSummaryDTO":{"type":"object","properties":{"name":{"type":"string","description":"Name of the deleted entity"}},"description":"Summary of a delete operation containing metadata about the deleted entity"},"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 ## POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/agents/check-identifier > Check if an agent identifier is already in use ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Agent Controller","description":"Management for creating, listing, finding, updating and deleting Agents"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/agents/check-identifier":{"post":{"tags":["Agent Controller"],"summary":"Check if an agent identifier is already in use","operationId":"checkIdentifier_2","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/CheckValueDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsedValueDTO"}}}},"400":{"description":"Bad Request","content":{"application/json":{"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":{"CheckValueDTO":{"required":["value"],"type":"object","properties":{"value":{"type":"string","description":"The value to be checked"},"uuid":{"type":"string","description":"Optional unique identifier of an associated entity"}},"description":"Data Transfer Object used to validate and check the existence or usage of a specific value"},"UsedValueDTO":{"type":"object","properties":{"used":{"type":"boolean","description":"Indicates whether the value is already in use"}},"description":"Data Transfer Object representing the result of checking if a value is already in use"},"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"}}}}}} ``` ## Persona ### Pagination and Listings ## GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/personas > Searches and paginates through personas ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Persona Controller","description":"Management for creating, listing, finding, updating and deleting Personas"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/personas":{"get":{"tags":["Persona Controller"],"summary":"Searches and paginates through personas","operationId":"page_1","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"}},{"name":"page","in":"query","description":"Current page, starting at 1","required":false,"schema":{"type":"integer","format":"int32","default":1}},{"name":"size","in":"query","description":"Size of the page","required":false,"schema":{"type":"integer","format":"int32","default":5}},{"name":"orderBy","in":"query","description":"The field to order results by","required":false,"schema":{"type":"string","default":"updatedAt"}},{"name":"direction","in":"query","description":"The sort direction (ASC or DESC)","required":false,"schema":{"type":"string","default":"DESC"}},{"name":"searchTerm","in":"query","description":"Optional search term to filter results","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"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":{"Page":{"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":{"type":"object"}},"number":{"type":"integer","format":"int32"},"sort":{"$ref":"#/components/schemas/SortObject"},"first":{"type":"boolean"},"last":{"type":"boolean"},"empty":{"type":"boolean"}}},"PageableObject":{"type":"object","properties":{"unpaged":{"type":"boolean"},"pageNumber":{"type":"integer","format":"int32"},"paged":{"type":"boolean"},"pageSize":{"type":"integer","format":"int32"},"offset":{"type":"integer","format":"int64"},"sort":{"$ref":"#/components/schemas/SortObject"}}},"SortObject":{"type":"object","properties":{"unsorted":{"type":"boolean"},"sorted":{"type":"boolean"},"empty":{"type":"boolean"}}},"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}/personas/quicksearch > Perform a quick search for persona names ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Persona Controller","description":"Management for creating, listing, finding, updating and deleting Personas"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/personas/quicksearch":{"get":{"tags":["Persona Controller"],"summary":"Perform a quick search for persona names","operationId":"quicksearch","parameters":[{"name":"x-request-id","in":"header","required":false,"schema":{"type":"string"}},{"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"}},{"name":"name","in":"query","description":"The name to search for","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"The maximum number of results to return","required":false,"schema":{"type":"integer","format":"int32","default":6}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"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":{"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":{"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}/personas/dropdown > Retrieve a list of personas for dropdown ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Persona Controller","description":"Management for creating, listing, finding, updating and deleting Personas"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/personas/dropdown":{"get":{"tags":["Persona Controller"],"summary":"Retrieve a list of personas for dropdown","operationId":"dropdown","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":{"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":{"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":{"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}/personas > Create a new persona ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Persona Controller","description":"Management for creating, listing, finding, updating and deleting Personas"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/personas":{"post":{"tags":["Persona Controller"],"summary":"Create a new persona","operationId":"create","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/CrudPersonaDTO"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaDTO"}}}},"400":{"description":"Bad Request","content":{"application/json":{"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":{"CrudPersonaDTO":{"required":["name"],"type":"object","properties":{"name":{"type":"string","description":"Name of the persona"},"image":{"type":"string","description":"Image URL or base64 encoded image for the persona"},"backstory":{"type":"string","description":"Backstory of the persona"},"personality":{"type":"string","description":"Personality traits of the persona"},"communicationStyle":{"type":"string","description":"Different styles of communication.","enum":["POLITE_AND_PERSUASIVE","WITTY_AND_CASUAL","EMPATHETIC_AND_HELPFUL","CONCISE_AND_PROFESSIONAL","FRIENDLY_AND_APPROACHABLE"]}},"description":"Data Transfer Object representing the fields for creating or updating a persona"},"PersonaDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the persona"},"name":{"type":"string","description":"Name of the persona"},"image":{"type":"string","description":"Image URL for the persona's avatar"},"backstory":{"type":"string","description":"Backstory of the persona"},"personality":{"type":"string","description":"Personality traits of the persona"},"communicationStyle":{"type":"string","description":"Different styles of communication.","enum":["POLITE_AND_PERSUASIVE","WITTY_AND_CASUAL","EMPATHETIC_AND_HELPFUL","CONCISE_AND_PROFESSIONAL","FRIENDLY_AND_APPROACHABLE"]},"agents":{"type":"array","description":"List of agents that use this persona","items":{"$ref":"#/components/schemas/BasicAgentDTO"}}},"description":"Data Transfer Object representing a Persona with all its attributes and associated agents"},"BasicAgentDTO":{"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"}},"description":"Data Transfer Object for Basic Agent Information"},"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}/personas/{personaUUID} > Retrieve a persona by its UUID ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Persona Controller","description":"Management for creating, listing, finding, updating and deleting Personas"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/personas/{personaUUID}":{"get":{"tags":["Persona Controller"],"summary":"Retrieve a persona by its UUID","operationId":"findByUUID_1","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"}},{"name":"personaUUID","in":"path","description":"The specific persona UUID to retrieve","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaDTO"}}}},"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":{"application/json":{"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":{"PersonaDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the persona"},"name":{"type":"string","description":"Name of the persona"},"image":{"type":"string","description":"Image URL for the persona's avatar"},"backstory":{"type":"string","description":"Backstory of the persona"},"personality":{"type":"string","description":"Personality traits of the persona"},"communicationStyle":{"type":"string","description":"Different styles of communication.","enum":["POLITE_AND_PERSUASIVE","WITTY_AND_CASUAL","EMPATHETIC_AND_HELPFUL","CONCISE_AND_PROFESSIONAL","FRIENDLY_AND_APPROACHABLE"]},"agents":{"type":"array","description":"List of agents that use this persona","items":{"$ref":"#/components/schemas/BasicAgentDTO"}}},"description":"Data Transfer Object representing a Persona with all its attributes and associated agents"},"BasicAgentDTO":{"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"}},"description":"Data Transfer Object for Basic Agent Information"},"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}/personas/{personaUUID} > Update an existing persona by its UUID ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Persona Controller","description":"Management for creating, listing, finding, updating and deleting Personas"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/personas/{personaUUID}":{"put":{"tags":["Persona Controller"],"summary":"Update an existing persona by its UUID","operationId":"update_1","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"}},{"name":"personaUUID","in":"path","description":"The specific persona UUID to update","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrudPersonaDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonaDTO"}}}},"400":{"description":"Bad Request","content":{"application/json":{"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":{"application/json":{"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":{"CrudPersonaDTO":{"required":["name"],"type":"object","properties":{"name":{"type":"string","description":"Name of the persona"},"image":{"type":"string","description":"Image URL or base64 encoded image for the persona"},"backstory":{"type":"string","description":"Backstory of the persona"},"personality":{"type":"string","description":"Personality traits of the persona"},"communicationStyle":{"type":"string","description":"Different styles of communication.","enum":["POLITE_AND_PERSUASIVE","WITTY_AND_CASUAL","EMPATHETIC_AND_HELPFUL","CONCISE_AND_PROFESSIONAL","FRIENDLY_AND_APPROACHABLE"]}},"description":"Data Transfer Object representing the fields for creating or updating a persona"},"PersonaDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the persona"},"name":{"type":"string","description":"Name of the persona"},"image":{"type":"string","description":"Image URL for the persona's avatar"},"backstory":{"type":"string","description":"Backstory of the persona"},"personality":{"type":"string","description":"Personality traits of the persona"},"communicationStyle":{"type":"string","description":"Different styles of communication.","enum":["POLITE_AND_PERSUASIVE","WITTY_AND_CASUAL","EMPATHETIC_AND_HELPFUL","CONCISE_AND_PROFESSIONAL","FRIENDLY_AND_APPROACHABLE"]},"agents":{"type":"array","description":"List of agents that use this persona","items":{"$ref":"#/components/schemas/BasicAgentDTO"}}},"description":"Data Transfer Object representing a Persona with all its attributes and associated agents"},"BasicAgentDTO":{"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"}},"description":"Data Transfer Object for Basic Agent Information"},"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}/personas/{personaUUID} > Delete a persona by its UUID ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Persona Controller","description":"Management for creating, listing, finding, updating and deleting Personas"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/personas/{personaUUID}":{"delete":{"tags":["Persona Controller"],"summary":"Delete a persona by its UUID","operationId":"delete","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"}},{"name":"personaUUID","in":"path","description":"The specific persona UUID to delete","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSummaryDTO"}}}},"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":{"application/json":{"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":{"DeleteSummaryDTO":{"type":"object","properties":{"name":{"type":"string","description":"Name of the deleted entity"}},"description":"Summary of a delete operation containing metadata about the deleted entity"},"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 ## POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/personas/check-identifier > Check if a persona identifier is already in use ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Persona Controller","description":"Management for creating, listing, finding, updating and deleting Personas"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/personas/check-identifier":{"post":{"tags":["Persona Controller"],"summary":"Check if a persona identifier is already in use","operationId":"checkIdentifier","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/CheckValueDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsedValueDTO"}}}},"400":{"description":"Bad Request","content":{"application/json":{"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":{"CheckValueDTO":{"required":["value"],"type":"object","properties":{"value":{"type":"string","description":"The value to be checked"},"uuid":{"type":"string","description":"Optional unique identifier of an associated entity"}},"description":"Data Transfer Object used to validate and check the existence or usage of a specific value"},"UsedValueDTO":{"type":"object","properties":{"used":{"type":"boolean","description":"Indicates whether the value is already in use"}},"description":"Data Transfer Object representing the result of checking if a value is already in use"},"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}/personas/summary > Retrieve persona summary information ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Persona Controller","description":"Management for creating, listing, finding, updating and deleting Personas"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/personas/summary":{"get":{"tags":["Persona Controller"],"summary":"Retrieve persona summary information","operationId":"summary","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/SummaryDTO"}}}},"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":{"SummaryDTO":{"type":"object","properties":{"used":{"type":"integer","description":"Number of resources currently used","format":"int32"},"limit":{"type":"integer","description":"Maximum allowable limit for the resource","format":"int32"}},"description":"Data Transfer Object representing a summary of usage and limits for a resource"},"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"}}}}}} ``` ## Function ### Pagination and Listings ## GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/functions > Searches and paginates through functions ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Function Controller","description":"Management for creating, listing, finding, updating and deleting Functions"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/functions":{"get":{"tags":["Function Controller"],"summary":"Searches and paginates through functions","operationId":"page_2","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"}},{"name":"page","in":"query","description":"Current page, starting at 1","required":false,"schema":{"type":"integer","format":"int32","default":1}},{"name":"size","in":"query","description":"Size of the page","required":false,"schema":{"type":"integer","format":"int32","default":5}},{"name":"orderBy","in":"query","description":"Field to sort by","required":false,"schema":{"type":"string","default":"updatedAt"}},{"name":"direction","in":"query","description":"Sort direction (ASC or DESC)","required":false,"schema":{"type":"string","default":"DESC"}},{"name":"searchTerm","in":"query","description":"Search term for filtering","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"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":{"Page":{"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":{"type":"object"}},"number":{"type":"integer","format":"int32"},"sort":{"$ref":"#/components/schemas/SortObject"},"first":{"type":"boolean"},"last":{"type":"boolean"},"empty":{"type":"boolean"}}},"PageableObject":{"type":"object","properties":{"unpaged":{"type":"boolean"},"pageNumber":{"type":"integer","format":"int32"},"paged":{"type":"boolean"},"pageSize":{"type":"integer","format":"int32"},"offset":{"type":"integer","format":"int64"},"sort":{"$ref":"#/components/schemas/SortObject"}}},"SortObject":{"type":"object","properties":{"unsorted":{"type":"boolean"},"sorted":{"type":"boolean"},"empty":{"type":"boolean"}}},"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}/functions/quicksearch > Perform a quick search for function names ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Function Controller","description":"Management for creating, listing, finding, updating and deleting Functions"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/functions/quicksearch":{"get":{"tags":["Function Controller"],"summary":"Perform a quick search for function names","operationId":"quicksearch_1","parameters":[{"name":"x-request-id","in":"header","required":false,"schema":{"type":"string"}},{"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"}},{"name":"name","in":"query","description":"Name to filter","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of results to return","required":false,"schema":{"type":"integer","format":"int32","default":6}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"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":{"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":{"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}/functions > Create a new function ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Function Controller","description":"Management for creating, listing, finding, updating and deleting Functions"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/functions":{"post":{"tags":["Function Controller"],"summary":"Create a new function","operationId":"create_1","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/CreateFunctionDTO"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunctionDTO"}}}},"400":{"description":"Bad Request","content":{"application/json":{"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":{"CreateFunctionDTO":{"required":["description","name"],"type":"object","properties":{"name":{"type":"string","description":"Name of the function"},"description":{"maxLength":1024,"minLength":0,"type":"string","description":"Description of the function"},"tags":{"type":"array","description":"List of tags associated with the function","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameterJson":{"type":"string","description":"JSON string representing function parameters"},"parameters":{"type":"array","description":"List of function parameters","items":{"$ref":"#/components/schemas/CreateFunctionParameterDTO"}}},"description":"Data Transfer Object representing the creation of an Agent Function"},"TagSimpleDTO":{"required":["name"],"type":"object","properties":{"uuid":{"type":"string","description":"Uuid of the tag, if existing. Not required, but will speed up the creation if present."},"name":{"type":"string","description":"Name of the tag. Expected to be in a '#term' format, hash included."}},"description":"Simplified structure representing a tag only by name and uuid"},"CreateFunctionParameterDTO":{"required":["description","name","type"],"type":"object","properties":{"name":{"type":"string","description":"The name of the parameter, must not be blank"},"type":{"type":"string","description":"Enumeration of parameter types for agent functions","enum":["STRING","NUMBER","BOOLEAN"]},"description":{"type":"string","description":"A description of the parameter, must not be blank"},"variable":{"type":"string","description":"An optional variable name associated with the parameter"},"rules":{"type":"array","description":"A list of rules associated with the parameter","items":{"$ref":"#/components/schemas/CreateRuleDTO"}}},"description":"DTO for creating function parameters"},"CreateRuleDTO":{"required":["value"],"type":"object","properties":{"value":{"type":"string","description":"The rule value, which is required and cannot be blank."}},"description":"Data Transfer Object for creating a rule associated with an agentic function parameter."},"FunctionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the function"},"name":{"type":"string","description":"Name of the function"},"description":{"type":"string","description":"Description of the function"},"agents":{"type":"array","description":"List of agents that can use this function","items":{"$ref":"#/components/schemas/BasicAgentDTO"}},"tags":{"type":"array","description":"List of tags associated with the function","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameterJson":{"type":"string","description":"JSON string representing function parameters"},"parameters":{"type":"array","description":"List of function parameters","items":{"$ref":"#/components/schemas/FunctionParameterDTO"}}},"description":"Data Transfer Object that encapsulates the details of a function"},"BasicAgentDTO":{"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"}},"description":"Data Transfer Object for Basic Agent Information"},"FunctionParameterDTO":{"required":["description","name","type"],"type":"object","properties":{"uuid":{"type":"string","description":"Uuid of the function parameter"},"name":{"type":"string","description":"Name of the function parameter"},"type":{"type":"string","description":"Enumeration of parameter types for agent functions","enum":["STRING","NUMBER","BOOLEAN"]},"description":{"type":"string","description":"Description of the function parameter"},"variable":{"type":"string","description":"Variable associated with the function parameter"},"rules":{"type":"array","description":"List of rules associated with the function parameter","items":{"$ref":"#/components/schemas/RuleDTO"}}},"description":"Data Transfer Object for function parameters"},"RuleDTO":{"required":["value"],"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the rule"},"value":{"type":"string","description":"Value associated with the rule"}},"description":"Data Transfer Object for Rule"},"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}/functions/{functionUUID} > Find a function by its UUID ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Function Controller","description":"Management for creating, listing, finding, updating and deleting Functions"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/functions/{functionUUID}":{"get":{"tags":["Function Controller"],"summary":"Find a function by its UUID","operationId":"findByUUID_2","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"}},{"name":"functionUUID","in":"path","description":"Function UUID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunctionDTO"}}}},"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":{"application/json":{"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":{"FunctionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the function"},"name":{"type":"string","description":"Name of the function"},"description":{"type":"string","description":"Description of the function"},"agents":{"type":"array","description":"List of agents that can use this function","items":{"$ref":"#/components/schemas/BasicAgentDTO"}},"tags":{"type":"array","description":"List of tags associated with the function","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameterJson":{"type":"string","description":"JSON string representing function parameters"},"parameters":{"type":"array","description":"List of function parameters","items":{"$ref":"#/components/schemas/FunctionParameterDTO"}}},"description":"Data Transfer Object that encapsulates the details of a function"},"BasicAgentDTO":{"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"}},"description":"Data Transfer Object for Basic Agent Information"},"TagSimpleDTO":{"required":["name"],"type":"object","properties":{"uuid":{"type":"string","description":"Uuid of the tag, if existing. Not required, but will speed up the creation if present."},"name":{"type":"string","description":"Name of the tag. Expected to be in a '#term' format, hash included."}},"description":"Simplified structure representing a tag only by name and uuid"},"FunctionParameterDTO":{"required":["description","name","type"],"type":"object","properties":{"uuid":{"type":"string","description":"Uuid of the function parameter"},"name":{"type":"string","description":"Name of the function parameter"},"type":{"type":"string","description":"Enumeration of parameter types for agent functions","enum":["STRING","NUMBER","BOOLEAN"]},"description":{"type":"string","description":"Description of the function parameter"},"variable":{"type":"string","description":"Variable associated with the function parameter"},"rules":{"type":"array","description":"List of rules associated with the function parameter","items":{"$ref":"#/components/schemas/RuleDTO"}}},"description":"Data Transfer Object for function parameters"},"RuleDTO":{"required":["value"],"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the rule"},"value":{"type":"string","description":"Value associated with the rule"}},"description":"Data Transfer Object for Rule"},"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}/functions/{functionUUID} > Update an existing function by its UUID ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Function Controller","description":"Management for creating, listing, finding, updating and deleting Functions"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/functions/{functionUUID}":{"put":{"tags":["Function Controller"],"summary":"Update an existing function by its UUID","operationId":"update_2","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"}},{"name":"functionUUID","in":"path","description":"Function UUID to update","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFunctionDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunctionDTO"}}}},"400":{"description":"Bad Request","content":{"application/json":{"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":{"application/json":{"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":{"UpdateFunctionDTO":{"required":["description","name"],"type":"object","properties":{"name":{"type":"string","description":"Name of the function"},"description":{"maxLength":1024,"minLength":0,"type":"string","description":"Description of the function"},"tags":{"type":"array","description":"List of tags associated with the function","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameterJson":{"type":"string","description":"JSON string representing function parameters"},"parameters":{"type":"array","description":"List of function parameters","items":{"$ref":"#/components/schemas/FunctionParameterDTO"}}},"description":"Data Transfer Object for updating an existing agent function"},"TagSimpleDTO":{"required":["name"],"type":"object","properties":{"uuid":{"type":"string","description":"Uuid of the tag, if existing. Not required, but will speed up the creation if present."},"name":{"type":"string","description":"Name of the tag. Expected to be in a '#term' format, hash included."}},"description":"Simplified structure representing a tag only by name and uuid"},"FunctionParameterDTO":{"required":["description","name","type"],"type":"object","properties":{"uuid":{"type":"string","description":"Uuid of the function parameter"},"name":{"type":"string","description":"Name of the function parameter"},"type":{"type":"string","description":"Enumeration of parameter types for agent functions","enum":["STRING","NUMBER","BOOLEAN"]},"description":{"type":"string","description":"Description of the function parameter"},"variable":{"type":"string","description":"Variable associated with the function parameter"},"rules":{"type":"array","description":"List of rules associated with the function parameter","items":{"$ref":"#/components/schemas/RuleDTO"}}},"description":"Data Transfer Object for function parameters"},"RuleDTO":{"required":["value"],"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier for the rule"},"value":{"type":"string","description":"Value associated with the rule"}},"description":"Data Transfer Object for Rule"},"FunctionDTO":{"type":"object","properties":{"uuid":{"type":"string","description":"Unique identifier of the function"},"name":{"type":"string","description":"Name of the function"},"description":{"type":"string","description":"Description of the function"},"agents":{"type":"array","description":"List of agents that can use this function","items":{"$ref":"#/components/schemas/BasicAgentDTO"}},"tags":{"type":"array","description":"List of tags associated with the function","items":{"$ref":"#/components/schemas/TagSimpleDTO"}},"parameterJson":{"type":"string","description":"JSON string representing function parameters"},"parameters":{"type":"array","description":"List of function parameters","items":{"$ref":"#/components/schemas/FunctionParameterDTO"}}},"description":"Data Transfer Object that encapsulates the details of a function"},"BasicAgentDTO":{"type":"object","properties":{"role":{"type":"string","description":"The role of the agent"}},"description":"Data Transfer Object for Basic Agent Information"},"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}/functions/{functionUUID} > Delete a function by its UUID ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Function Controller","description":"Management for creating, listing, finding, updating and deleting Functions"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/functions/{functionUUID}":{"delete":{"tags":["Function Controller"],"summary":"Delete a function by its UUID","operationId":"delete_1","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"}},{"name":"functionUUID","in":"path","description":"Function UUID to delete","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSummaryDTO"}}}},"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":{"application/json":{"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":{"DeleteSummaryDTO":{"type":"object","properties":{"name":{"type":"string","description":"Name of the deleted entity"}},"description":"Summary of a delete operation containing metadata about the deleted entity"},"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 ## POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/functions/check-identifier > Check if a function identifier is already in use ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Function Controller","description":"Management for creating, listing, finding, updating and deleting Functions"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/functions/check-identifier":{"post":{"tags":["Function Controller"],"summary":"Check if a function identifier is already in use","operationId":"checkIdentifier_1","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/CheckValueDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsedValueDTO"}}}},"400":{"description":"Bad Request","content":{"application/json":{"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":{"CheckValueDTO":{"required":["value"],"type":"object","properties":{"value":{"type":"string","description":"The value to be checked"},"uuid":{"type":"string","description":"Optional unique identifier of an associated entity"}},"description":"Data Transfer Object used to validate and check the existence or usage of a specific value"},"UsedValueDTO":{"type":"object","properties":{"used":{"type":"boolean","description":"Indicates whether the value is already in use"}},"description":"Data Transfer Object representing the result of checking if a value is already in use"},"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"}}}}}} ``` ## Variable ### Auxiliary Methods ## POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/variables > Check if a variable is currently in use within a bot's configuration ```json {"openapi":"3.0.1","info":{"title":"eva-generative-service API Documentation","version":"4.8.0"},"tags":[{"name":"Variable Controller","description":"Management for validating bot variables"}],"paths":{"/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/variables":{"post":{"tags":["Variable Controller"],"summary":"Check if a variable is currently in use within a bot's configuration","operationId":"checkFunctionVariable","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/CheckValueDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsedValueDTO"}}}},"400":{"description":"Bad Request","content":{"application/json":{"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":{"CheckValueDTO":{"required":["value"],"type":"object","properties":{"value":{"type":"string","description":"The value to be checked"},"uuid":{"type":"string","description":"Optional unique identifier of an associated entity"}},"description":"Data Transfer Object used to validate and check the existence or usage of a specific value"},"UsedValueDTO":{"type":"object","properties":{"used":{"type":"boolean","description":"Indicates whether the value is already in use"}},"description":"Data Transfer Object representing the result of checking if a value is already in use"},"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: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.conversational-ai.syntphony.com/user-guide/api-docs/api-guidelines/management-api/instance-api/agent.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.