# Broker

The broker API is responsible for managing the conversations performed by your users. While it is listed here, we encourage you to visit it's [specific page](/user-guide/api-docs/api-guidelines/creating-channels-the-conversation-api.md#what-is-the-conversation-api) for a complete orientation of how to use it.

### Conversation Methods

{% openapi src="/files/pqzbnGOEf5nrfeohw2cj" path="/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/channel/{channelUUID}/v1/conversations" method="post" %}
[eva-broker-4.7.0.yaml](https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FjDtCvq6alIqtj29o77bV%2Feva-broker-4.7.0.yaml?alt=media\&token=c0cd154d-8448-4ceb-94da-cf627a3bcf0c)
{% endopenapi %}

{% openapi src="/files/pqzbnGOEf5nrfeohw2cj" path="/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/channel/{channelUUID}/v1/conversations/{sessionCode}" method="post" %}
[eva-broker-4.7.0.yaml](https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FjDtCvq6alIqtj29o77bV%2Feva-broker-4.7.0.yaml?alt=media\&token=c0cd154d-8448-4ceb-94da-cf627a3bcf0c)
{% endopenapi %}

{% openapi src="/files/pqzbnGOEf5nrfeohw2cj" path="/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/conversations/{sessionCode}/satisfactions" method="post" %}
[eva-broker-4.7.0.yaml](https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FjDtCvq6alIqtj29o77bV%2Feva-broker-4.7.0.yaml?alt=media\&token=c0cd154d-8448-4ceb-94da-cf627a3bcf0c)
{% endopenapi %}

### API Key

## GET /org/{orgUUID}/env/{envUUID}/api-key

> Retrieves the API key for the specified organization and environment.

```json
{"openapi":"3.0.1","info":{"title":"eva-broker API Documentation","version":"4.8.0"},"tags":[{"name":"Api Key","description":"Controller for managing API keys."}],"paths":{"/org/{orgUUID}/env/{envUUID}/api-key":{"get":{"tags":["Api Key"],"summary":"Retrieves the API key for the specified organization and environment.","operationId":"getApiKey","parameters":[{"name":"orgUUID","in":"path","description":"A valid organization UUID","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid environment UUID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiKeyDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"ApiKeyDTO":{"type":"object","properties":{"apiKey":{"type":"string"}}},"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"}}}}}}
```

### Likable

## POST /org/{orgUUID}/env/{envUUID}/likable

> Save user's evaluation

```json
{"openapi":"3.0.1","info":{"title":"eva-broker API Documentation","version":"4.8.0"},"tags":[{"name":"Likable","description":"Controller for handling likable actions"}],"paths":{"/org/{orgUUID}/env/{envUUID}/likable":{"post":{"tags":["Likable"],"summary":"Save user's evaluation","operationId":"conversation","parameters":[{"name":"API-KEY","in":"header","description":"The API key from the request header for authorization","required":true,"schema":{"type":"string"}},{"name":"orgUUID","in":"path","description":"A valid organization UUID","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid environment UUID","required":true,"schema":{"type":"string"}},{"name":"requesterId","in":"query","description":"Query parameter for the requester ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LikableRequestBodyDTO"}}},"required":true},"responses":{"200":{"description":"Ok","content":{"*/*":{"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":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"LikableRequestBodyDTO":{"type":"object","properties":{"evaluation":{"type":"boolean","description":"Indicates whether the interaction should be evaluated."},"interactionId":{"type":"string","description":"Unique identifier for the interaction."}},"description":"Contain customer satisfaction data"},"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"}}}}}}
```

### History

## GET /org/{orgUUID}/env/{envUUID}/history/{businessKey}

> Get conversation history

```json
{"openapi":"3.0.1","info":{"title":"eva-broker API Documentation","version":"4.8.0"},"tags":[{"name":"History","description":"Controller for managing conversation history"}],"paths":{"/org/{orgUUID}/env/{envUUID}/history/{businessKey}":{"get":{"tags":["History"],"summary":"Get conversation history","operationId":"getHistory","parameters":[{"name":"businessKey","in":"path","description":"The business key to retrieve history","required":true,"schema":{"type":"string"}},{"name":"orgUUID","in":"path","description":"A valid organization UUID","required":true,"schema":{"type":"string"}},{"name":"envUUID","in":"path","description":"A valid environment UUID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/HistoryResponseDTO"}}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"401":{"description":"Unauthorized","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"403":{"description":"Forbidden","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"408":{"description":"Request Timeout","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"409":{"description":"Conflict","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}},"422":{"description":"Unprocessable Entity","content":{"*/*":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/StandardError"}]}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}},"components":{"schemas":{"HistoryResponseDTO":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/SessionDTO"},"userInteractions":{"type":"array","description":"A list of user interactions associated with the session.","items":{"$ref":"#/components/schemas/UserInteractionDTO"}}},"description":"Represents the response containing session and user interactions."},"SessionDTO":{"type":"object","properties":{"sessionCode":{"type":"string","description":"Unique code identifying the session"},"createDate":{"type":"string","description":"The date and time when the session was created","format":"date-time"},"expireDate":{"type":"string","description":"The date and time when the session will expire","format":"date-time"},"businessKey":{"type":"string","description":"Business key associated with the session"},"sessionType":{"type":"string","description":"Type of the session","enum":["CREATED","UPDATED","EXPIRED"]},"botId":{"type":"string","description":"Identifier for the bot associated with the session"},"channelId":{"type":"string","description":"Identifier for the communication channel"},"operatingSystem":{"type":"string","description":"Operating system on which the session is running"},"operatingSystemVersion":{"type":"string","description":"Version of the operating system"},"browser":{"type":"string","description":"Name of the web browser used"},"browserVersion":{"type":"string","description":"Version of the web browser being used"},"userRef":{"type":"string","description":"Reference identifier for the user"},"locale":{"type":"string","description":"Locale settings for the session"},"test":{"type":"boolean","description":"Indicates if this session is a test session"}},"description":"Representation of a session in the application"},"UserInteractionDTO":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the user interaction.","format":"int64"},"createDate":{"type":"string","description":"Date and time when the interaction was created.","format":"date-time"},"sessionCode":{"type":"string","description":"Code representing the user session."},"userSent":{"type":"boolean","description":"Indicates if the user sent the input."},"answerUuid":{"type":"string","description":"UUID corresponding to the answer provided."},"text":{"type":"string","description":"The text input provided by the user."},"intent":{"type":"string","description":"Intent inferred from the user input."},"confidence":{"type":"number","description":"Confidence level of the intent detection.","format":"double"},"entities":{"type":"string","description":"Entities extracted from the user's input."},"userSentId":{"type":"string","description":"Unique ID of the user who sent the input."},"evaluation":{"type":"boolean","description":"Indicates whether the interaction has been evaluated."},"uuid":{"type":"string","description":"UUID for the user interaction."}},"description":"Data transfer object for user interaction."},"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/broker.md?ask=<question>
```

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.