# Conversation

## Get conversations

> Retrieve conversations in an organization based on supplied filters.\
> \
> \#### Permissions\
> This endpoint may be impacted by the following permissions:\
> \* The \`final\_message\` field in the response is only non-empty if the authenticated user has the \`Conversation.GetMessage\` permission on the final message.\
> \* The \`version\_set\_info\` field in the response is only non-empty if the authenticated user has the \`Service.GetVersionSet\` permission on the version set.\
> \* Only conversations for which the user has the \`Conversation.GetConversation\` permission are returned.

```json
{"openapi":"3.1.0","info":{"title":"Amigo API","version":"0.1.0"},"servers":[{"url":"https://api.amigo.ai"},{"url":"https://internal-api.amigo.ai"},{"url":"https://api-eu-central-1.amigo.ai"},{"url":"https://api-ap-southeast-2.amigo.ai"},{"url":"https://api-ca-central-1.amigo.ai"}],"security":[{"Bearer-Authorization":[],"Bearer-Authorization-Organization":[],"Basic":[]}],"components":{"securitySchemes":{"Bearer-Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint."}},"schemas":{"src__app__endpoints__conversation__get_conversations__Response":{"properties":{"conversations":{"items":{"$ref":"#/components/schemas/ConversationInstance"},"type":"array","title":"Conversations","description":"The conversations satisfying the filters."},"has_more":{"type":"boolean","title":"Has More","description":"Whether there are more conversations to retrieve."},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token","description":"A token to supply to the next request to retrieve the next page of conversations. Only populated if `has_more` is `True`."}},"type":"object","required":["conversations","has_more","continuation_token"],"title":"Response"},"ConversationInstance":{"properties":{"id":{"type":"string","title":"Id","description":"The identifier of the conversation."},"user_id":{"type":"string","title":"User Id","description":"The identifier of the user who started this conversation."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The timestamp at which this conversation was started."},"is_finished":{"type":"boolean","title":"Is Finished","description":"Whether the conversation is finished."},"is_analyzed":{"type":"boolean","title":"Is Analyzed","description":"Whether the conversation has gone through the post-conversation analysis after finishing."},"completed_post_processings":{"items":{"$ref":"#/components/schemas/PostAnalysisType"},"type":"array","title":"Completed Post Processings","description":"A list of post-processing types that have been completed for this conversation."},"final_message":{"type":"string","title":"Final Message","description":"The most recent message from the conversation.\n\nThis field is empty if the authenticated user has no `Conversation:GetMessage` permission on the final message."},"service_id":{"type":"string","title":"Service Id","description":"The ID of the service that this conversation uses."},"version_set_info":{"anyOf":[{"$ref":"#/components/schemas/VersionSetInfo"},{"type":"null"}],"description":"Info of the service version set that this conversation uses. This field is only populated if the authenticated user has the `Service.GetVersionSet` permission on the version set."},"num_messages":{"type":"integer","title":"Num Messages","description":"The number of messages in this conversation."},"tags":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object","title":"Tags","description":"The tags associated with this conversation."}},"type":"object","required":["id","user_id","created_at","is_finished","is_analyzed","completed_post_processings","final_message","service_id","version_set_info","num_messages","tags"],"title":"ConversationInstance"},"PostAnalysisType":{"type":"string","enum":["generate-user-models","extract-memories","compute-metrics"]},"VersionSetInfo":{"properties":{"name":{"type":"string","title":"Name","description":"The name of the version set. If the value is `unknown`, it means the conversation was created before this field was introduced and the version set name cannot be retroactively determined."},"agent_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Agent Version Info","description":"The ID of the agent and version number used in this conversation."},"service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Service Hierarchical State Machine Version Info","description":"The ID of the state machine and version number used in this conversation."},"llm_model_preferences":{"additionalProperties":{"$ref":"#/components/schemas/LLMConfig-Output"},"type":"object","title":"Llm Model Preferences","description":"The LLM model preferences for this version set."}},"type":"object","required":["name","agent_version_info","service_hierarchical_state_machine_version_info","llm_model_preferences"],"title":"VersionSetInfo"},"LLMConfig-Output":{"properties":{"llm_name":{"type":"string","title":"Llm Name","description":"The name of the LLM to use."},"params":{"additionalProperties":true,"type":"object","title":"Params","description":"LLM-specific parameters to use.","default":{}}},"type":"object","required":["llm_name"],"title":"LLMConfig"}}},"paths":{"/v1/{organization}/conversation/":{"get":{"tags":["Conversation"],"summary":"Get conversations","description":"Retrieve conversations in an organization based on supplied filters.\n\n#### Permissions\nThis endpoint may be impacted by the following permissions:\n* The `final_message` field in the response is only non-empty if the authenticated user has the `Conversation.GetMessage` permission on the final message.\n* The `version_set_info` field in the response is only non-empty if the authenticated user has the `Service.GetVersionSet` permission on the version set.\n* Only conversations for which the user has the `Conversation.GetConversation` permission are returned.","operationId":"get-conversations","parameters":[{"name":"organization","in":"path","required":true,"schema":{"type":"string","title":"Organization"}},{"name":"user_id","in":"query","required":false,"schema":{"type":"array","uniqueItems":true,"items":{"type":"string"},"description":"The identifier of the user whose conversations to retrieve.","default":[],"title":"User Id"},"description":"The identifier of the user whose conversations to retrieve."},{"name":"service_id","in":"query","required":false,"schema":{"type":"array","uniqueItems":true,"items":{"type":"string","pattern":"^[a-f0-9]{24}$"},"description":"The identifier of the service whose conversation to retrieve.","default":[],"title":"Service Id"},"description":"The identifier of the service whose conversation to retrieve."},{"name":"is_finished","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether the conversation is finished.","title":"Is Finished"},"description":"Whether the conversation is finished."},{"name":"id","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","pattern":"^[a-f0-9]{24}$"},"description":"The ID of the conversation to retrieve.","default":[],"title":"Id"},"description":"The ID of the conversation to retrieve."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":150,"exclusiveMinimum":0,"description":"The maximum number of conversations to retrieve.","default":150,"title":"Limit"},"description":"The maximum number of conversations to retrieve."},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","description":"The continuation token returned from the previous response to retrieve the next set of conversations.","default":0,"title":"Continuation Token"},"description":"The continuation token returned from the previous response to retrieve the next set of conversations."},{"name":"sort_by","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"The field to sort the conversations by. Supported fields are `created_at`. Specify a `+` before the field name to indicate ascending sorting and `-` for descending sorting. Multiple fields can be specified to break ties.","default":[],"title":"Sort By"},"description":"The field to sort the conversations by. Supported fields are `created_at`. Specify a `+` before the field name to indicate ascending sorting and `-` for descending sorting. Multiple fields can be specified to break ties."},{"name":"tag","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"The tags of the dynamic behavior sets. Must be specified using the syntax `key:value`, which means to match all sets with the given `key` and `value` pair among its tags. If `value` is `*`, it means the `value` does not matter. If `value` is empty, it matches against when the value is `None`.","default":[],"title":"Tag"},"description":"The tags of the dynamic behavior sets. Must be specified using the syntax `key:value`, which means to match all sets with the given `key` and `value` pair among its tags. If `value` is `*`, it means the `value` does not matter. If `value` is empty, it matches against when the value is `None`."},{"name":"x-mongo-cluster-name","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.","title":"X-Mongo-Cluster-Name"},"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database."},{"name":"Sec-WebSocket-Protocol","in":"header","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Sec-Websocket-Protocol"}}],"responses":{"200":{"description":"Succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__app__endpoints__conversation__get_conversations__Response"}}}},"401":{"description":"Invalid authorization credentials."},"403":{"description":"Missing required permissions."},"422":{"description":"Invalid request path parameter or query parameter failed validation."},"429":{"description":"The user has exceeded the rate limit of 15 requests per minute for this endpoint."},"503":{"description":"The service is going through temporary maintenance."}}}}}}
```

## Create a conversation

> Create a new conversation and start it. The user must not have any unfinished conversations that belong to the same service.\
> \
> \#### Permissions\
> This endpoint requires the following permissions:\
> \* \`Conversation:CreateConversation\` for the new conversation.\
> \
> This endpoint may be impacted by the following permissions:\
> \* \`CurrentAgentActionEvent\`s are only emitted if the authenticated user has the \`Conversation:GetInteractionInsights\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Amigo API","version":"0.1.0"},"servers":[{"url":"https://api.amigo.ai"},{"url":"https://internal-api.amigo.ai"},{"url":"https://api-eu-central-1.amigo.ai"},{"url":"https://api-ap-southeast-2.amigo.ai"},{"url":"https://api-ca-central-1.amigo.ai"}],"security":[{"Bearer-Authorization":[],"Bearer-Authorization-Organization":[],"Basic":[]}],"components":{"securitySchemes":{"Bearer-Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint."}},"schemas":{"src__app__endpoints__conversation__create_conversation__Request":{"properties":{"service_id":{"type":"string","pattern":"^[a-f0-9]{24}$","title":"Service Id","description":"The identifier of the service to create a conversation in."},"service_version_set_name":{"type":"string","title":"Service Version Set Name","description":"The version set of the service to use. If not provided, the `release` version set is used.","default":"release"},"initial_message":{"anyOf":[{"$ref":"#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__1"},{"type":"null"}],"description":"The initial user or agent inner thought message to send to the service. If not provided, the conversation will start with an agent message."},"initial_message_type":{"anyOf":[{"type":"string","enum":["user-message","external-event"]},{"type":"null"}],"title":"Initial Message Type","description":"The type of the `initial_message`. Can only be specified if `initial_message` is provided."},"tags":{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__4"},{"type":"null"}]},"propertyNames":{"$ref":"#/components/schemas/StrippedNonemptyString___w__s______"},"type":"object","maxProperties":20,"title":"Tags","description":"A list of tags for the conversation. The key can only contain alphanumeric characters, underscores, or spaces. The value can only contain up to 100 characters.","default":{}}},"type":"object","required":["service_id"],"title":"Request"},"amigo_lib__pydantic__base_model__StrippedNonemptyString__1":{"type":"string","minLength":1},"amigo_lib__pydantic__base_model__StrippedNonemptyString__4":{"type":"string","maxLength":100,"minLength":1},"StrippedNonemptyString___w__s______":{"type":"string","minLength":1,"pattern":"^[\\w\\s_]+$"},"src__app__endpoints__conversation__create_conversation__Response":{"oneOf":[{"$ref":"#/components/schemas/ConversationCreatedEvent"},{"$ref":"#/components/schemas/NewMessageEvent"},{"$ref":"#/components/schemas/InteractionCompleteEvent"},{"$ref":"#/components/schemas/CurrentAgentActionEvent"},{"$ref":"#/components/schemas/ErrorEvent"}],"discriminator":{"propertyName":"type","mapping":{"conversation-created":"#/components/schemas/ConversationCreatedEvent","current-agent-action":"#/components/schemas/CurrentAgentActionEvent","error":"#/components/schemas/ErrorEvent","interaction-complete":"#/components/schemas/InteractionCompleteEvent","new-message":"#/components/schemas/NewMessageEvent"}}},"ConversationCreatedEvent":{"properties":{"type":{"type":"string","const":"conversation-created","title":"Type","default":"conversation-created"},"conversation_id":{"type":"string","title":"Conversation Id","description":"The identifier of the newly created conversation."}},"type":"object","required":["conversation_id"],"title":"ConversationCreatedEvent","description":"Emitted when the conversation is created."},"NewMessageEvent":{"properties":{"type":{"type":"string","const":"new-message","title":"Type","default":"new-message"},"message":{"type":"string","title":"Message","description":"Either the raw-text piece or a base-64 encoded string of bytes representing the piece in alternative forms. If it represents audio, the audios are in\nPCM16 format."},"transcript_alignment":{"anyOf":[{"items":{"prefixItems":[{"type":"integer"},{"type":"string"}],"type":"array","maxItems":2,"minItems":2},"type":"array"},{"type":"null"}],"title":"Transcript Alignment","description":"Transcript of the ongoing audio message and how they align with the audio, if the message is in audio format. Otherwise, it's `None`. This is an array of tuples, where each tuple contains\na character and an integer indicating the milliseconds since the audio started when the character is spoken.\n\nNote that this field might not be defined for some events that transmit audio bytes -- in that case, the alignment information for that chunk was already\nincluded in the `transcript_alignment` field in the previous event."},"stop":{"type":"boolean","title":"Stop","description":"Whether this is the last piece of the agent message."},"sequence_number":{"type":"integer","title":"Sequence Number","description":"The sequence number of this piece in the agent message."},"message_id":{"type":"string","title":"Message Id","description":"The identifier of this agent message. "}},"type":"object","required":["message","transcript_alignment","stop","sequence_number","message_id"],"title":"NewMessageEvent","description":"Emitted when a new piece of the agent message is available."},"InteractionCompleteEvent":{"properties":{"type":{"type":"string","const":"interaction-complete","title":"Type","default":"interaction-complete"},"message_id":{"type":"string","title":"Message Id","description":"The identifier of the agent message in this interaction."},"interaction_id":{"type":"string","title":"Interaction Id","description":"The identifier of this interaction."},"full_message":{"type":"string","title":"Full Message","description":"A structure containing either the content of the message if it's text, or the transcript of the message if it's audio."},"conversation_completed":{"type":"boolean","title":"Conversation Completed","description":"Whether the conversation is auto-completed after this interaction."}},"type":"object","required":["message_id","interaction_id","full_message","conversation_completed"],"title":"InteractionCompleteEvent","description":"Emitted when the interaction is complete and committed to database. This event is only emitted after all `NewMessageEvent`s are emitted."},"CurrentAgentActionEvent":{"properties":{"type":{"type":"string","const":"current-agent-action","title":"Type","default":"current-agent-action"},"action":{"$ref":"#/components/schemas/src__app__amigo__service__conversation__Action","description":"The type of action the agent is performing right now."}},"type":"object","required":["action"],"title":"CurrentAgentActionEvent","description":"Emitted when an agent is about to perform an action that aids in the generation of the response. This is emitted before any\n`NewMessageEvent` is emitted."},"src__app__amigo__service__conversation__Action":{"anyOf":[{"$ref":"#/components/schemas/SelectDynamicBehaviorAgentActionEvent"},{"$ref":"#/components/schemas/CheckIfActiveMemoryNeededAgentActionEvent"},{"$ref":"#/components/schemas/ExtractActiveMemoriesAgentActionEvent"},{"$ref":"#/components/schemas/NavigateStateMachineAgentActionEvent"},{"$ref":"#/components/schemas/EngageUserAgentActionEvent"}]},"SelectDynamicBehaviorAgentActionEvent":{"oneOf":[{"$ref":"#/components/schemas/SelectDynamicBehaviorVectorGeneratedEvent"},{"$ref":"#/components/schemas/SelectDynamicBehaviorRelevanceRetrievalCompletedEvent"},{"$ref":"#/components/schemas/SelectDynamicBehaviorCompletedEvent"}],"discriminator":{"propertyName":"type","mapping":{"select-dynamic-behavior-completed":"#/components/schemas/SelectDynamicBehaviorCompletedEvent","select-dynamic-behavior-relevance-retrieval-completed":"#/components/schemas/SelectDynamicBehaviorRelevanceRetrievalCompletedEvent","select-dynamic-behavior-vector-generated":"#/components/schemas/SelectDynamicBehaviorVectorGeneratedEvent"}}},"SelectDynamicBehaviorVectorGeneratedEvent":{"properties":{"type":{"type":"string","const":"select-dynamic-behavior-vector-generated","title":"Type","default":"select-dynamic-behavior-vector-generated"}},"type":"object","title":"SelectDynamicBehaviorVectorGeneratedEvent"},"SelectDynamicBehaviorRelevanceRetrievalCompletedEvent":{"properties":{"type":{"type":"string","const":"select-dynamic-behavior-relevance-retrieval-completed","title":"Type","default":"select-dynamic-behavior-relevance-retrieval-completed"}},"type":"object","title":"SelectDynamicBehaviorRelevanceRetrievalCompletedEvent"},"SelectDynamicBehaviorCompletedEvent":{"properties":{"type":{"type":"string","const":"select-dynamic-behavior-completed","title":"Type","default":"select-dynamic-behavior-completed"},"selected_dynamic_behavior_set_version_info":{"anyOf":[{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2},{"type":"null"}],"title":"Selected Dynamic Behavior Set Version Info"},"previous_selected_dynamic_behavior_set_version_info":{"anyOf":[{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2},{"type":"null"}],"title":"Previous Selected Dynamic Behavior Set Version Info"}},"type":"object","required":["selected_dynamic_behavior_set_version_info","previous_selected_dynamic_behavior_set_version_info"],"title":"SelectDynamicBehaviorCompletedEvent"},"CheckIfActiveMemoryNeededAgentActionEvent":{"properties":{"type":{"type":"string","const":"check-if-active-memory-needed-completed","title":"Type","default":"check-if-active-memory-needed-completed"},"queries":{"items":{"type":"string"},"type":"array","title":"Queries"}},"type":"object","required":["queries"],"title":"CheckIfActiveMemoryNeededCompletedEvent"},"ExtractActiveMemoriesAgentActionEvent":{"properties":{"type":{"type":"string","const":"extract-active-memories-completed","title":"Type","default":"extract-active-memories-completed"},"queries_and_responses":{"items":{"prefixItems":[{"type":"string"},{"type":"string"}],"type":"array","maxItems":2,"minItems":2},"type":"array","title":"Queries And Responses"}},"type":"object","required":["queries_and_responses"],"title":"ExtractActiveMemoriesCompletedEvent"},"NavigateStateMachineAgentActionEvent":{"anyOf":[{"$ref":"#/components/schemas/NavigateStateMachineDynamicBehaviorOverrideEvent"},{"$ref":"#/components/schemas/NavigateStateMachineActionStateActionSelectedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineDecisionStateDecisionStartedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineExitConditionSelectedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineRecallStateDynamicQueriesGeneratedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineRecallStateStaticQueriesRetrievedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineRecallStateActiveMemoryRetrievedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineReflectionStatePromptRetrievedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineReflectionStateReflectionGeneratedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineAnnotationStateAnnotationRetrievedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineStateTransitionedEvent"},{"$ref":"#/components/schemas/GenerateToolParamsEvent"},{"$ref":"#/components/schemas/NavigateStateMachineToolCallStateToolOutputAvailableEvent"},{"$ref":"#/components/schemas/ToolCallStartedEvent"},{"$ref":"#/components/schemas/ToolCallEndedEvent"},{"$ref":"#/components/schemas/ActionTooLongEvent"}]},"NavigateStateMachineDynamicBehaviorOverrideEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-dynamic-behavior-override","title":"Type","default":"navigate-state-machine-dynamic-behavior-override"},"overriding_instructions":{"type":"boolean","title":"Overriding Instructions","description":"Whether the dynamic behavior set is overriding instructions during this interaction."},"overriding_tool_candidates":{"type":"boolean","title":"Overriding Tool Candidates","description":"Whether the dynamic behavior set is overriding the tool candidates during this interaction."}},"type":"object","required":["overriding_instructions","overriding_tool_candidates"],"title":"NavigateStateMachineDynamicBehaviorOverrideEvent","description":"Indicating that the agent has merged the dynamic behavior set's instructions with the instructions from the current state."},"NavigateStateMachineActionStateActionSelectedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-action-state-action-selected","title":"Type","default":"navigate-state-machine-action-state-action-selected"},"action":{"type":"string","title":"Action"}},"type":"object","required":["action"],"title":"NavigateStateMachineActionStateActionSelectedEvent","description":"Indicating that the agent has selected an action from the current state."},"NavigateStateMachineDecisionStateDecisionStartedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-decision-state-decision-started","title":"Type","default":"navigate-state-machine-decision-state-decision-started"}},"type":"object","title":"NavigateStateMachineDecisionStateDecisionStartedEvent","description":"Indicating that the agent has started making a decision in the current decision state."},"NavigateStateMachineExitConditionSelectedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-exit-condition-selected","title":"Type","default":"navigate-state-machine-exit-condition-selected"},"exit_condition":{"type":"string","title":"Exit Condition","description":"The exit condition that the agent has selected."},"next_state_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next State State Machine Version Info","description":"The state machine version info of the next state."},"next_state_name":{"type":"string","title":"Next State Name","description":"The name of the next state."}},"type":"object","required":["exit_condition","next_state_state_machine_version_info","next_state_name"],"title":"NavigateStateMachineExitConditionSelectedEvent","description":"Indicating that the agent has selected an exit condition from the current action or decision state."},"NavigateStateMachineRecallStateDynamicQueriesGeneratedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-recall-state-dynamic-queries-generated","title":"Type","default":"navigate-state-machine-recall-state-dynamic-queries-generated"},"dynamic_queries":{"items":{"type":"string"},"type":"array","title":"Dynamic Queries","description":"The dynamic queries that the agent has generated."},"requested_information":{"type":"string","title":"Requested Information","description":"The information that the agent needs from the queries."}},"type":"object","required":["dynamic_queries","requested_information"],"title":"NavigateStateMachineRecallStateDynamicQueriesGeneratedEvent","description":"Indicating that the agent has generated dynamic queries in the current the recall state."},"NavigateStateMachineRecallStateStaticQueriesRetrievedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-recall-state-static-queries-retrieved","title":"Type","default":"navigate-state-machine-recall-state-static-queries-retrieved"},"static_queries":{"items":{"type":"string"},"type":"array","title":"Static Queries","description":"The static queries that the agent has retrieved."}},"type":"object","required":["static_queries"],"title":"NavigateStateMachineRecallStateStaticQueriesRetrievedEvent","description":"Indicating that the agent has retrieved the static queries in the current the recall state."},"NavigateStateMachineRecallStateActiveMemoryRetrievedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-recall-state-active-memory-retrieved","title":"Type","default":"navigate-state-machine-recall-state-active-memory-retrieved"},"queries_and_responses":{"items":{"prefixItems":[{"type":"string"},{"type":"string"}],"type":"array","maxItems":2,"minItems":2},"type":"array","title":"Queries And Responses","description":"A list of tuples of queries and responses."}},"type":"object","required":["queries_and_responses"],"title":"NavigateStateMachineRecallStateActiveMemoryRetrievedEvent","description":"Indicating that the agent has retrieved the active memory in the current the recall state."},"NavigateStateMachineReflectionStatePromptRetrievedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-reflection-state-prompt-retrieved","title":"Type","default":"navigate-state-machine-reflection-state-prompt-retrieved"},"prompt":{"type":"string","title":"Prompt"}},"type":"object","required":["prompt"],"title":"NavigateStateMachineReflectionStatePromptRetrievedEvent","description":"Indicating that the agent has retrieved the prompt in the current reflection state."},"NavigateStateMachineReflectionStateReflectionGeneratedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-reflection-state-reflection-generated","title":"Type","default":"navigate-state-machine-reflection-state-reflection-generated"},"reflection":{"type":"string","title":"Reflection","description":"The reflection that the agent has generated."}},"type":"object","required":["reflection"],"title":"NavigateStateMachineReflectionStateReflectionGeneratedEvent","description":"Indicating that the agent has generated the reflection in the current reflection state."},"NavigateStateMachineAnnotationStateAnnotationRetrievedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-annotation-state-annotation-retrieved","title":"Type","default":"navigate-state-machine-annotation-state-annotation-retrieved"},"annotation":{"type":"string","title":"Annotation"}},"type":"object","required":["annotation"],"title":"NavigateStateMachineAnnotationStateAnnotationRetrievedEvent","description":"Indicating that the agent has retrieved the annotation in the current annotation state."},"NavigateStateMachineStateTransitionedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-state-transitioned","title":"Type","default":"navigate-state-machine-state-transitioned"},"prev_state":{"type":"string","title":"Prev State","description":"The previous state."},"prev_state_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Prev State State Machine Version Info","description":"The state machine version info of the previous state."},"next_state":{"type":"string","title":"Next State","description":"The next state."},"next_state_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next State State Machine Version Info","description":"The state machine version info of the next state."}},"type":"object","required":["prev_state","prev_state_state_machine_version_info","next_state","next_state_state_machine_version_info"],"title":"NavigateStateMachineStateTransitionedEvent","description":"Indicating that the agent has transitioned to a new state."},"GenerateToolParamsEvent":{"anyOf":[{"$ref":"#/components/schemas/GenerateToolParamsDesignatedToolRetrievedEvent"},{"$ref":"#/components/schemas/GenerateToolParamsDesignatedToolCallParamsGeneratedEvent"},{"$ref":"#/components/schemas/ActionTooLongEvent"},{"$ref":"#/components/schemas/ToolCallStartedEvent"},{"$ref":"#/components/schemas/ToolCallEndedEvent"}]},"GenerateToolParamsDesignatedToolRetrievedEvent":{"properties":{"type":{"type":"string","const":"designated-tool-retrieved","title":"Type","default":"designated-tool-retrieved"},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."}},"type":"object","required":["tool_id","tool_version"],"title":"GenerateToolParamsDesignatedToolRetrievedEvent"},"GenerateToolParamsDesignatedToolCallParamsGeneratedEvent":{"properties":{"type":{"type":"string","const":"designated-tool-call-params-generated","title":"Type","default":"designated-tool-call-params-generated"},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."},"tool_call_params":{"additionalProperties":true,"type":"object","title":"Tool Call Params","description":"The generated tool call parameters."}},"type":"object","required":["tool_id","tool_version","tool_call_params"],"title":"GenerateToolParamsDesignatedToolCallParamsGeneratedEvent"},"ActionTooLongEvent":{"properties":{"type":{"type":"string","const":"action-too-long","title":"Type","default":"action-too-long"},"filler":{"type":"string","title":"Filler","description":"A filler that can be played while waiting for the action to complete. If the audio filler exists, this is monochannel, 16-bit PCM WAV audio (at sample rate 16kHz) encoded in base64 encoding.\nOtherwise, this is the text corresponding to the audio filler."},"previously_started_event":{"title":"Previously Started Event","description":"The previously started event that is taking too long."}},"type":"object","required":["filler","previously_started_event"],"title":"ActionTooLongEvent","description":"Indicating that a previously-started action of the agent is taking too long. This event supplies a filler text that can be displayed\nwhile waiting for the action to complete."},"ToolCallStartedEvent":{"properties":{"type":{"type":"string","const":"tool-call-started","title":"Type","default":"tool-call-started"},"tool_round_index":{"type":"integer","title":"Tool Round Index","description":"Within the current LLM interaction, the round of tool call."},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."},"input_params":{"additionalProperties":true,"type":"object","title":"Input Params","description":"The input parameters for the tool call."}},"type":"object","required":["tool_round_index","tool_id","tool_version","input_params"],"title":"ToolCallStartedEvent","description":"Indicating that the agent has started executing a tool."},"ToolCallEndedEvent":{"properties":{"type":{"type":"string","const":"tool-call-ended","title":"Type","default":"tool-call-ended"},"tool_round_index":{"type":"integer","title":"Tool Round Index","description":"Within the current LLM interaction, the round of tool call."},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."},"input_parameters":{"additionalProperties":true,"type":"object","title":"Input Parameters","description":"The input parameters for the tool call."},"result":{"type":"string","title":"Result","description":"The result of the tool call."},"duration":{"type":"number","title":"Duration","description":"The duration of the tool call in seconds."}},"type":"object","required":["tool_round_index","tool_id","tool_version","input_parameters","result","duration"],"title":"ToolCallEndedEvent","description":"Indicating that the agent has finished executing a tool."},"NavigateStateMachineToolCallStateToolOutputAvailableEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-tool-call-state-tool-output-available","title":"Type","default":"navigate-state-machine-tool-call-state-tool-output-available"},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."},"tool_output":{"type":"string","title":"Tool Output","description":"The tool output."},"duration":{"type":"number","title":"Duration","description":"The duration taken to receive the tool output in seconds."},"input_arguments":{"additionalProperties":true,"type":"object","title":"Input Arguments","description":"The input arguments used for the tool call."}},"type":"object","required":["tool_id","tool_version","tool_output","duration","input_arguments"],"title":"NavigateStateMachineToolCallStateToolOutputAvailableEvent","description":"Indicating that the agent has received the tool output in the current tool call state."},"EngageUserAgentActionEvent":{"oneOf":[{"$ref":"#/components/schemas/EngageUserDynamicBehaviorOverrideEvent"},{"$ref":"#/components/schemas/EngageUserMessageFragmentGeneratedEvent"},{"$ref":"#/components/schemas/ToolCallStartedEvent"},{"$ref":"#/components/schemas/ToolCallEndedEvent"},{"$ref":"#/components/schemas/ActionTooLongEvent"}],"discriminator":{"propertyName":"type","mapping":{"action-too-long":"#/components/schemas/ActionTooLongEvent","engage-user-dynamic-behavior-override":"#/components/schemas/EngageUserDynamicBehaviorOverrideEvent","engage-user-message-fragment-generated":"#/components/schemas/EngageUserMessageFragmentGeneratedEvent","tool-call-ended":"#/components/schemas/ToolCallEndedEvent","tool-call-started":"#/components/schemas/ToolCallStartedEvent"}}},"EngageUserDynamicBehaviorOverrideEvent":{"properties":{"type":{"type":"string","const":"engage-user-dynamic-behavior-override","title":"Type","default":"engage-user-dynamic-behavior-override"},"overriding_instructions":{"type":"boolean","title":"Overriding Instructions","description":"Whether the dynamic behavior set is overriding instructions during this interaction."},"overriding_tool_candidates":{"type":"boolean","title":"Overriding Tool Candidates","description":"Whether the dynamic behavior set is overriding the tool candidates during this interaction."}},"type":"object","required":["overriding_instructions","overriding_tool_candidates"],"title":"EngageUserDynamicBehaviorOverrideEvent","description":"Indicating that the agent has merged the dynamic behavior set's instructions with the instructions from the current state."},"EngageUserMessageFragmentGeneratedEvent":{"properties":{"type":{"type":"string","const":"engage-user-message-fragment-generated","title":"Type","default":"engage-user-message-fragment-generated"},"index":{"type":"integer","title":"Index","description":"The index of the fragment in the agent response."},"fragment":{"type":"string","title":"Fragment","description":"The fragment of the agent response that has been generated."},"is_final":{"type":"boolean","title":"Is Final","description":"Whether this fragment is the final fragment of the agent response."}},"type":"object","required":["index","fragment","is_final"],"title":"EngageUserMessageFragmentGeneratedEvent","description":"Indicating that the agent has generated a fragment of the agent response."},"ErrorEvent":{"properties":{"type":{"type":"string","const":"error","title":"Type","default":"error"},"http_error_code":{"type":"integer","title":"Http Error Code","description":"The HTTP status code of the error."},"error_description":{"type":"string","title":"Error Description","description":"A description of the error."}},"type":"object","required":["http_error_code","error_description"],"title":"ErrorEvent","description":"Emitted when there is an error during the stream. This event could be emitted even if the request returns with a 200.\nIf received before an `interaction-complete` event, the client should consider the entire interaction void and retry. If received after,\nthen the conversation has completed and an error occurred during the post-processing, so the client should consider the interaction valid and saved,\nbut manually call the `FinishConversation` endpoint to retry the post-processing."}}},"paths":{"/v1/{organization}/conversation/":{"post":{"tags":["Conversation"],"summary":"Create a conversation","description":"Create a new conversation and start it. The user must not have any unfinished conversations that belong to the same service.\n\n#### Permissions\nThis endpoint requires the following permissions:\n* `Conversation:CreateConversation` for the new conversation.\n\nThis endpoint may be impacted by the following permissions:\n* `CurrentAgentActionEvent`s are only emitted if the authenticated user has the `Conversation:GetInteractionInsights` permission.","operationId":"create-conversation","parameters":[{"name":"organization","in":"path","required":true,"schema":{"type":"string","title":"Organization"}},{"name":"response_format","in":"query","required":true,"schema":{"enum":["text","voice"],"type":"string","description":"The format of the response that will be sent to the user.","title":"Response Format"},"description":"The format of the response that will be sent to the user."},{"name":"current_agent_action_type","in":"query","required":false,"schema":{"type":"string","description":"A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`.","default":"^.*$","title":"Current Agent Action Type"},"description":"A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`."},{"name":"x-mongo-cluster-name","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.","title":"X-Mongo-Cluster-Name"},"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database."},{"name":"Sec-WebSocket-Protocol","in":"header","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Sec-Websocket-Protocol"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__app__endpoints__conversation__create_conversation__Request"}}}},"responses":{"201":{"description":"\nSucceeded. The response will be a stream of events in JSON format separated by newlines. The server will transmit an event as soon as one is available,\nso the client should respond to the events as soon as one arrives, and keep listening until the server closes the connection.\n","content":{"application/x-ndjson":{"schema":{"type":"object","$ref":"#/components/schemas/src__app__endpoints__conversation__create_conversation__Response"}}}},"400":{"description":"\nThis may occur for the following reasons:\n* Attempting to start a conversation when other unfinished conversations exist.\n* The preferred language does not support voice response.\n* The `response_audio_format` field is not set when voice output is requested.\n* The agent does not have voice config specified."},"401":{"description":"Invalid authorization credentials."},"403":{"description":"Missing required permissions."},"404":{"description":"Specified organization, service, or version set is not found."},"409":{"description":"A related operation is in progress."},"422":{"description":"Invalid request path parameter or request body failed validation."},"429":{"description":"The user has exceeded the rate limit of 5 requests per minute for this endpoint."},"503":{"description":"The service is going through temporary maintenance."}}}}}}
```

## Get conversation messages

> Retrieve messages in a conversation, sorted in the specified order, up to the specified limit.\
> \
> \#### Permissions\
> This endpoint is impacted by the following permissions:\
> \* Only messages that the authenticated user has \`Conversation.GetMessage\` permission on will be returned.

```json
{"openapi":"3.1.0","info":{"title":"Amigo API","version":"0.1.0"},"servers":[{"url":"https://api.amigo.ai"},{"url":"https://internal-api.amigo.ai"},{"url":"https://api-eu-central-1.amigo.ai"},{"url":"https://api-ap-southeast-2.amigo.ai"},{"url":"https://api-ca-central-1.amigo.ai"}],"security":[{"Bearer-Authorization":[],"Bearer-Authorization-Organization":[],"Basic":[]}],"components":{"securitySchemes":{"Bearer-Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint."}},"schemas":{"MessageType":{"type":"string","enum":["user-message","agent-message","agent-inner-thought","external-event"]},"src__app__endpoints__conversation__get_conversation_messages__Response":{"properties":{"messages":{"items":{"$ref":"#/components/schemas/MessageInstance"},"type":"array","title":"Messages","description":"The retrieved messages."},"has_more":{"type":"boolean","title":"Has More","description":"Whether there are more, earlier messages in the conversation to retrieve."},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token","description":"The continuation token to use to retrieve the next set of messages."}},"type":"object","required":["messages","has_more","continuation_token"],"title":"Response"},"MessageInstance":{"properties":{"id":{"type":"string","title":"Id"},"interaction_id":{"type":"string","title":"Interaction Id","description":"The identifier of the interaction."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"The time at which this message was created."},"sender":{"type":"string","title":"Sender","description":"A human-friendly name of the sender of the message."},"message":{"type":"string","title":"Message","description":"The text content of the message."},"format":{"$ref":"#/components/schemas/Format","description":"The format in which the message was delivered."},"message_type":{"$ref":"#/components/schemas/MessageType","description":"The type of the message."}},"type":"object","required":["id","interaction_id","created_at","sender","message","format","message_type"],"title":"MessageInstance"},"Format":{"type":"string","enum":["text","voice"]}}},"paths":{"/v1/{organization}/conversation/{conversation_id}/messages/":{"get":{"tags":["Conversation"],"summary":"Get conversation messages","description":"Retrieve messages in a conversation, sorted in the specified order, up to the specified limit.\n\n#### Permissions\nThis endpoint is impacted by the following permissions:\n* Only messages that the authenticated user has `Conversation.GetMessage` permission on will be returned.","operationId":"get-conversation-messages","parameters":[{"name":"organization","in":"path","required":true,"schema":{"type":"string","title":"Organization"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"The identifier of the conversation.","title":"Conversation Id"},"description":"The identifier of the conversation."},{"name":"id","in":"query","required":false,"schema":{"type":"array","uniqueItems":true,"items":{"type":"string","pattern":"^[a-f0-9]{24}$"},"description":"The IDs of the messages to retrieve.","default":[],"title":"Id"},"description":"The IDs of the messages to retrieve."},{"name":"message_type","in":"query","required":false,"schema":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/MessageType"},"description":"The type of messages to retrieve.","default":["external-event","agent-message","user-message"],"title":"Message Type"},"description":"The type of messages to retrieve."},{"name":"interaction_id","in":"query","required":false,"schema":{"type":"array","uniqueItems":true,"items":{"type":"string","pattern":"^[a-f0-9]{24}$"},"description":"The IDs of the interactions to retrieve messages for.","default":[],"title":"Interaction Id"},"description":"The IDs of the interactions to retrieve messages for."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"exclusiveMinimum":0,"description":"The maximum number of messages to return. At most 500 messages can be returned in one request.","default":500,"title":"Limit"},"description":"The maximum number of messages to return. At most 500 messages can be returned in one request."},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","description":"The continuation token to use to retrieve the next set of messages.","default":0,"title":"Continuation Token"},"description":"The continuation token to use to retrieve the next set of messages."},{"name":"sort_by","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"The field to sort the messages by. Supported fields are `interaction_id` and `created_at`. Specify a `+` before the field name to indicate ascending sorting and `-` for descending sorting. Multiple fields can be specified to break ties.","default":[],"title":"Sort By"},"description":"The field to sort the messages by. Supported fields are `interaction_id` and `created_at`. Specify a `+` before the field name to indicate ascending sorting and `-` for descending sorting. Multiple fields can be specified to break ties."},{"name":"x-mongo-cluster-name","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.","title":"X-Mongo-Cluster-Name"},"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database."},{"name":"Sec-WebSocket-Protocol","in":"header","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Sec-Websocket-Protocol"}}],"responses":{"200":{"description":"Succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__app__endpoints__conversation__get_conversation_messages__Response"}}}},"401":{"description":"Invalid authorization credentials."},"403":{"description":"Missing required permissions."},"404":{"description":"Specified organization or conversation is not found."},"422":{"description":"Invalid request path parameter failed validation."},"429":{"description":"The user has exceeded the rate limit of 20 requests per minute for this endpoint."},"503":{"description":"The service is going through temporary maintenance."}}}}}}
```

## Finish a conversation

> Conclude a conversation and asynchronously initiate post-conversation analysis.\
> \
> This endpoint should only be called on a started, non-finished conversation. It can only be called when the previous \[\`Start a conversation\`]\(start-conversation) and\
> \[\`Interact with a conversation\`]\(interact-with-conversation) calls have finished.\
> \
> If the conversation has no messages, the conversation is deleted.\
> \
> It's possible for some conversations to automatically finish during an \[\`Interact with a conversation\`]\(interact-with-conversation) call (for instance, if the user explicitly sends a message\
> indicating that they're done with the conversation). In that case, this endpoint shouldn't be called, as the \[\`Interact with a conversation\`]\(interact-with-conversation) endpoint automatically\
> wraps up the conversation.\
> \
> \#### Permissions\
> This endpoint requires the following permissions:\
> \* \`User:UpdateUserInfo\` on the user who started the conversation.\
> \* \`Conversation:FinishConversation\` on the conversation.

```json
{"openapi":"3.1.0","info":{"title":"Amigo API","version":"0.1.0"},"servers":[{"url":"https://api.amigo.ai"},{"url":"https://internal-api.amigo.ai"},{"url":"https://api-eu-central-1.amigo.ai"},{"url":"https://api-ap-southeast-2.amigo.ai"},{"url":"https://api-ca-central-1.amigo.ai"}],"security":[{"Bearer-Authorization":[],"Bearer-Authorization-Organization":[],"Basic":[]}],"components":{"securitySchemes":{"Bearer-Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint."}}},"paths":{"/v1/{organization}/conversation/{conversation_id}/finish/":{"post":{"tags":["Conversation"],"summary":"Finish a conversation","description":"Conclude a conversation and asynchronously initiate post-conversation analysis.\n\nThis endpoint should only be called on a started, non-finished conversation. It can only be called when the previous [`Start a conversation`](start-conversation) and\n[`Interact with a conversation`](interact-with-conversation) calls have finished.\n\nIf the conversation has no messages, the conversation is deleted.\n\nIt's possible for some conversations to automatically finish during an [`Interact with a conversation`](interact-with-conversation) call (for instance, if the user explicitly sends a message\nindicating that they're done with the conversation). In that case, this endpoint shouldn't be called, as the [`Interact with a conversation`](interact-with-conversation) endpoint automatically\nwraps up the conversation.\n\n#### Permissions\nThis endpoint requires the following permissions:\n* `User:UpdateUserInfo` on the user who started the conversation.\n* `Conversation:FinishConversation` on the conversation.","operationId":"finish-conversation","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"The identifier of the conversation to finish.","title":"Conversation Id"},"description":"The identifier of the conversation to finish."},{"name":"organization","in":"path","required":true,"schema":{"type":"string","title":"Organization"}},{"name":"x-mongo-cluster-name","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.","title":"X-Mongo-Cluster-Name"},"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database."},{"name":"Sec-WebSocket-Protocol","in":"header","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Sec-Websocket-Protocol"}}],"responses":{"204":{"description":"Succeeded."},"400":{"description":"The conversation has no interactions."},"401":{"description":"Invalid authorization credentials."},"403":{"description":"Missing required permissions."},"404":{"description":"Specified organization or conversation is not found."},"409":{"description":"The specified conversation is already finished, or a related operation is in process."},"422":{"description":"Invalid request path parameter failed validation."},"429":{"description":"The user has exceeded the rate limit of 5 requests per minute for this endpoint."},"503":{"description":"The service is going through temporary maintenance."}}}}}}
```

## Recommend responses for interaction

> Generate a recommended response for the user to send based on the existing chat history. This should be called when the most recent interaction\
> had concluded for a while but the user still hasn't responded.\
> \
> \#### Permissions:\
> This endpoint requires the following permissions:\
> \* \`Conversation:GetRecommendedResponses\` on this conversation.

```json
{"openapi":"3.1.0","info":{"title":"Amigo API","version":"0.1.0"},"servers":[{"url":"https://api.amigo.ai"},{"url":"https://internal-api.amigo.ai"},{"url":"https://api-eu-central-1.amigo.ai"},{"url":"https://api-ap-southeast-2.amigo.ai"},{"url":"https://api-ca-central-1.amigo.ai"}],"security":[{"Bearer-Authorization":[],"Bearer-Authorization-Organization":[],"Basic":[]}],"components":{"securitySchemes":{"Bearer-Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint."}},"schemas":{"src__app__endpoints__conversation__recommend_responses_for_interaction__Request":{"properties":{"context":{"$ref":"#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__1","description":"The context under which the recommended responses should be generated.","default":"\nPERSONA:\nName: User\nBackground: A typical person seeking this service.\n---\nSCENARIO:\nName: Complete Service\nObjective: Successfully complete the service interaction.\nInstructions: Engage naturally with the agent to achieve the service objective.\n"}},"type":"object","title":"Request"},"amigo_lib__pydantic__base_model__StrippedNonemptyString__1":{"type":"string","minLength":1},"src__app__endpoints__conversation__recommend_responses_for_interaction__Response":{"properties":{"recommended_responses":{"items":{"type":"string"},"type":"array","title":"Recommended Responses","description":"The recommended responses to the user."}},"type":"object","required":["recommended_responses"],"title":"Response"}}},"paths":{"/v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/recommend_responses":{"post":{"tags":["Conversation"],"summary":"Recommend responses for interaction","description":"Generate a recommended response for the user to send based on the existing chat history. This should be called when the most recent interaction\nhad concluded for a while but the user still hasn't responded.\n\n#### Permissions:\nThis endpoint requires the following permissions:\n* `Conversation:GetRecommendedResponses` on this conversation.","operationId":"recommend-responses-for-interaction","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"The identifier of the conversation.","title":"Conversation Id"},"description":"The identifier of the conversation."},{"name":"interaction_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"The identifier of the most recent interaction.","title":"Interaction Id"},"description":"The identifier of the most recent interaction."},{"name":"organization","in":"path","required":true,"schema":{"type":"string","title":"Organization"}},{"name":"x-mongo-cluster-name","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.","title":"X-Mongo-Cluster-Name"},"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database."},{"name":"Sec-WebSocket-Protocol","in":"header","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Sec-Websocket-Protocol"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__app__endpoints__conversation__recommend_responses_for_interaction__Request","default":{"context":"\nPERSONA:\nName: User\nBackground: A typical person seeking this service.\n---\nSCENARIO:\nName: Complete Service\nObjective: Successfully complete the service interaction.\nInstructions: Engage naturally with the agent to achieve the service objective.\n"}}}}},"responses":{"200":{"description":"Succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__app__endpoints__conversation__recommend_responses_for_interaction__Response"}}}},"400":{"description":"The conversation is finished, or the supplied interaction ID doesn't correspond to the latest, completed interaction."},"401":{"description":"Invalid authorization credentials."},"403":{"description":"Missing required permissions."},"404":{"description":"Specified organization or conversation is not found."},"422":{"description":"Invalid request path parameter failed validation."},"429":{"description":"The user has exceeded the rate limit of 20 requests per minute for this endpoint."},"503":{"description":"The service is going through temporary maintenance."}}}}}}
```

## Get interaction insights

> Retrieve insights about the agent's message for a given interaction.\
> \
> \#### Permissions:\
> This endpoint requires the following permissions:\
> \* \`Conversation:GetInteractionInsights\` on the conversation.\
> \* \`Organization:GetServiceHierarchicalStateMachine\` on the state machine that the current interaction is in.\
> \
> This endpoint may be impacted by the following permissions:\
> \* Only reflection messages for which the authenticated user has the \`Conversation:GetMessage\` permission are included in the response.

```json
{"openapi":"3.1.0","info":{"title":"Amigo API","version":"0.1.0"},"servers":[{"url":"https://api.amigo.ai"},{"url":"https://internal-api.amigo.ai"},{"url":"https://api-eu-central-1.amigo.ai"},{"url":"https://api-ap-southeast-2.amigo.ai"},{"url":"https://api-ca-central-1.amigo.ai"}],"security":[{"Bearer-Authorization":[],"Bearer-Authorization-Organization":[],"Basic":[]}],"components":{"securitySchemes":{"Bearer-Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint."}},"schemas":{"src__app__endpoints__conversation__get_interaction_insights__Response":{"properties":{"current_state_name":{"type":"string","title":"Current State Name","description":"The state the agent is in."},"current_state_action":{"type":"string","title":"Current State Action","description":"The action taken in the current state."},"current_state_objective":{"type":"string","title":"Current State Objective","description":"The objective of the current state."},"state_transition_logs":{"items":{"$ref":"#/components/schemas/StateTransitionLog"},"type":"array","title":"State Transition Logs","description":"The state transition log of the interaction."},"working_memory":{"items":{"$ref":"#/components/schemas/WorkingMemory"},"type":"array","title":"Working Memory","description":"A list of active memories the agent used to generate the message."},"reflections":{"items":{"type":"string"},"type":"array","title":"Reflections","description":"A list of reflections the agent made during the generation of this message."},"triggered_dynamic_behavior_set_version_info":{"anyOf":[{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2},{"type":"null"}],"title":"Triggered Dynamic Behavior Set Version Info","description":"The ID and version number of the dynamic behavior set that was activated during this interaction."},"select_next_action_tool_call_logs":{"items":{"items":{"$ref":"#/components/schemas/ToolCallLog"},"type":"array"},"type":"array","title":"Select Next Action Tool Call Logs","description":"A list of tool call logs that were performed during the final `SelectNextAction` LLM call during this interaction where an action was selected."},"engage_user_tool_call_logs":{"items":{"items":{"$ref":"#/components/schemas/ToolCallLog"},"type":"array"},"type":"array","title":"Engage User Tool Call Logs","description":"A list of tool call logs that were performed during the `EngageUser` LLM call during this interaction."}},"type":"object","required":["current_state_name","current_state_action","current_state_objective","state_transition_logs","working_memory","reflections","triggered_dynamic_behavior_set_version_info","select_next_action_tool_call_logs","engage_user_tool_call_logs"],"title":"Response"},"StateTransitionLog":{"oneOf":[{"$ref":"#/components/schemas/ActionStateTransitionLog"},{"$ref":"#/components/schemas/DecisionStateTransitionLog"},{"$ref":"#/components/schemas/RecallStateTransitionLog"},{"$ref":"#/components/schemas/JumpbackStateTransitionLog"},{"$ref":"#/components/schemas/AnnotationStateTransitionLog"},{"$ref":"#/components/schemas/ReflectionStateTransitionLog"},{"$ref":"#/components/schemas/ToolCallStateTransitionLog"}],"discriminator":{"propertyName":"type","mapping":{"action":"#/components/schemas/ActionStateTransitionLog","annotation":"#/components/schemas/AnnotationStateTransitionLog","decision":"#/components/schemas/DecisionStateTransitionLog","jumpback":"#/components/schemas/JumpbackStateTransitionLog","recall":"#/components/schemas/RecallStateTransitionLog","reflection":"#/components/schemas/ReflectionStateTransitionLog","tool-call":"#/components/schemas/ToolCallStateTransitionLog"}}},"ActionStateTransitionLog":{"properties":{"previous_state":{"type":"string","title":"Previous State","description":"Name of the previous state to transition from."},"previous_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Previous Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the previous state is in."},"next_state":{"type":"string","title":"Next State","description":"Name of the next state to transition to."},"next_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the next state is in."},"type":{"type":"string","const":"action","title":"Type","description":"The type of the state transition log, which is the type of the state we're transitioning from.","default":"action"},"previous_state_exit_condition_description":{"type":"string","title":"Previous State Exit Condition Description","description":"The description of the exit condition that led to the transition to the next state."},"tool_call_logs":{"items":{"items":{"$ref":"#/components/schemas/ToolCallLog"},"type":"array"},"type":"array","title":"Tool Call Logs","description":"A list of tool call logs that were performed during the `SelectNextAction` LLM call during this state."}},"type":"object","required":["previous_state","previous_service_hierarchical_state_machine_version_info","next_state","next_service_hierarchical_state_machine_version_info","previous_state_exit_condition_description","tool_call_logs"],"title":"ActionStateTransitionLog"},"ToolCallLog":{"properties":{"tool_name":{"type":"string","title":"Tool Name","description":"The name of the tool that was called."},"tool_id":{"type":"string","title":"Tool Id","description":"The identifier of the tool that was called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool that was called."},"input":{"additionalProperties":true,"type":"object","title":"Input","description":"The input to the tool call."},"output":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output","description":"The output of the tool call. If `None`, the tool call's output is ephemeral and not stored."},"duration":{"type":"number","title":"Duration","description":"The duration of the tool call in seconds."}},"type":"object","required":["tool_name","tool_id","tool_version","input","output","duration"],"title":"ToolCallLog"},"DecisionStateTransitionLog":{"properties":{"previous_state":{"type":"string","title":"Previous State","description":"Name of the previous state to transition from."},"previous_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Previous Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the previous state is in."},"next_state":{"type":"string","title":"Next State","description":"Name of the next state to transition to."},"next_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the next state is in."},"type":{"type":"string","const":"decision","title":"Type","description":"The type of the state transition log, which is the type of the state we're transitioning from.","default":"decision"},"previous_state_exit_condition_description":{"type":"string","title":"Previous State Exit Condition Description","description":"The description of the exit condition that led to the transition to the next state."},"tool_call_logs":{"items":{"items":{"$ref":"#/components/schemas/ToolCallLog"},"type":"array"},"type":"array","title":"Tool Call Logs","description":"A list of tool call logs that were performed during the `SelectNextActionForDecisionState` LLM call during this state."}},"type":"object","required":["previous_state","previous_service_hierarchical_state_machine_version_info","next_state","next_service_hierarchical_state_machine_version_info","previous_state_exit_condition_description","tool_call_logs"],"title":"DecisionStateTransitionLog"},"RecallStateTransitionLog":{"properties":{"previous_state":{"type":"string","title":"Previous State","description":"Name of the previous state to transition from."},"previous_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Previous Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the previous state is in."},"next_state":{"type":"string","title":"Next State","description":"Name of the next state to transition to."},"next_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the next state is in."},"type":{"type":"string","const":"recall","title":"Type","description":"The type of the state transition log, which is the type of the state we're transitioning from.","default":"recall"},"performed_queries":{"items":{"type":"string"},"type":"array","title":"Performed Queries","description":"A list of queries that were actually performed during this state. This does not include queries included in the states that are duplicates of queries performed previously in this conversation."}},"type":"object","required":["previous_state","previous_service_hierarchical_state_machine_version_info","next_state","next_service_hierarchical_state_machine_version_info","performed_queries"],"title":"RecallStateTransitionLog"},"JumpbackStateTransitionLog":{"properties":{"previous_state":{"type":"string","title":"Previous State","description":"Name of the previous state to transition from."},"previous_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Previous Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the previous state is in."},"next_state":{"type":"string","title":"Next State","description":"Name of the next state to transition to."},"next_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the next state is in."},"type":{"type":"string","const":"jumpback","title":"Type","description":"The type of the state transition log, which is the type of the state we're transitioning from.","default":"jumpback"}},"type":"object","required":["previous_state","previous_service_hierarchical_state_machine_version_info","next_state","next_service_hierarchical_state_machine_version_info"],"title":"JumpbackStateTransitionLog"},"AnnotationStateTransitionLog":{"properties":{"previous_state":{"type":"string","title":"Previous State","description":"Name of the previous state to transition from."},"previous_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Previous Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the previous state is in."},"next_state":{"type":"string","title":"Next State","description":"Name of the next state to transition to."},"next_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the next state is in."},"type":{"type":"string","const":"annotation","title":"Type","description":"The type of the state transition log, which is the type of the state we're transitioning from.","default":"annotation"},"inner_thought_message_id":{"type":"string","title":"Inner Thought Message Id","description":"The identifier of the inserted inner thought message."}},"type":"object","required":["previous_state","previous_service_hierarchical_state_machine_version_info","next_state","next_service_hierarchical_state_machine_version_info","inner_thought_message_id"],"title":"AnnotationStateTransitionLog"},"ReflectionStateTransitionLog":{"properties":{"previous_state":{"type":"string","title":"Previous State","description":"Name of the previous state to transition from."},"previous_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Previous Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the previous state is in."},"next_state":{"type":"string","title":"Next State","description":"Name of the next state to transition to."},"next_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the next state is in."},"type":{"type":"string","const":"reflection","title":"Type","description":"The type of the state transition log, which is the type of the state we're transitioning from.","default":"reflection"},"inner_thought_message_id":{"type":"string","title":"Inner Thought Message Id","description":"The identifier of the inserted inner thought message."},"tool_call_logs":{"items":{"items":{"$ref":"#/components/schemas/ToolCallLog"},"type":"array"},"type":"array","title":"Tool Call Logs","description":"A list of tool call logs that were performed during the `GenerateReflection` LLM call during this state."}},"type":"object","required":["previous_state","previous_service_hierarchical_state_machine_version_info","next_state","next_service_hierarchical_state_machine_version_info","inner_thought_message_id","tool_call_logs"],"title":"ReflectionStateTransitionLog"},"ToolCallStateTransitionLog":{"properties":{"previous_state":{"type":"string","title":"Previous State","description":"Name of the previous state to transition from."},"previous_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Previous Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the previous state is in."},"next_state":{"type":"string","title":"Next State","description":"Name of the next state to transition to."},"next_service_hierarchical_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next Service Hierarchical State Machine Version Info","description":"The identifier of the service hierarchical state machine that the next state is in."},"type":{"type":"string","const":"tool-call","title":"Type","description":"The type of the state transition log, which is the type of the state we're transitioning from.","default":"tool-call"},"tool_call_logs":{"items":{"items":{"$ref":"#/components/schemas/ToolCallLog"},"type":"array"},"type":"array","title":"Tool Call Logs","description":"A list of tool call logs that were performed during this state, except for the tool call for the designated tool call."},"designated_tool_call_log":{"$ref":"#/components/schemas/ToolCallLog","description":"The tool call log for the designated tool call in this state."}},"type":"object","required":["previous_state","previous_service_hierarchical_state_machine_version_info","next_state","next_service_hierarchical_state_machine_version_info","tool_call_logs","designated_tool_call_log"],"title":"ToolCallStateTransitionLog"},"WorkingMemory":{"properties":{"content":{"type":"string","title":"Content","description":"The content of the memory."},"context":{"type":"string","title":"Context","description":"The context of the memory."}},"type":"object","required":["content","context"],"title":"WorkingMemory"}}},"paths":{"/v1/{organization}/conversation/{conversation_id}/interaction/{interaction_id}/insights":{"get":{"tags":["Conversation"],"summary":"Get interaction insights","description":"Retrieve insights about the agent's message for a given interaction.\n\n#### Permissions:\nThis endpoint requires the following permissions:\n* `Conversation:GetInteractionInsights` on the conversation.\n* `Organization:GetServiceHierarchicalStateMachine` on the state machine that the current interaction is in.\n\nThis endpoint may be impacted by the following permissions:\n* Only reflection messages for which the authenticated user has the `Conversation:GetMessage` permission are included in the response.","operationId":"get-interaction-insights","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"The identifier of the conversation.","title":"Conversation Id"},"description":"The identifier of the conversation."},{"name":"interaction_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"The identifier of the interaction.","title":"Interaction Id"},"description":"The identifier of the interaction."},{"name":"organization","in":"path","required":true,"schema":{"type":"string","title":"Organization"}},{"name":"x-mongo-cluster-name","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.","title":"X-Mongo-Cluster-Name"},"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database."},{"name":"Sec-WebSocket-Protocol","in":"header","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Sec-Websocket-Protocol"}}],"responses":{"200":{"description":"Succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__app__endpoints__conversation__get_interaction_insights__Response"}}}},"401":{"description":"Invalid authorization credentials."},"403":{"description":"Missing required permissions."},"404":{"description":"Specified organization, conversation, or interaction is not found."},"422":{"description":"Invalid request path parameter failed validation."},"429":{"description":"The user has exceeded the rate limit of 20 requests per minute for this endpoint."},"503":{"description":"The service is going through temporary maintenance."}}}}}}
```

## Interact with a conversation

> Send a new user message to the conversation. The endpoint will perform analysis and generate an agent message in response.\
> \
> A \`UserMessageAvailableEvent\` will be the first event in the response, which includes the user message if it's sent as text, or the transcribed message if it's sent as voice.\
> A series of \`CurrentAgentActionEvent\`s will follow, which indicates steps in the agent's thinking process. Then the agent message is generated sequentially in pieces, with each piece\
> being sent as a \`NewMessageEvent\` in the response. After all the pieces are sent, an \`InteractionCompleteEvent\` is sent. Depending on the \`conversation\_completed\` property in this event, the conversation will be awaiting\
> a new message from the user, or it might automatically end (for instance, because the user message indicates the user wants to end the session), while the conversation is marked as finished and the post-conversation\
> analysis asynchronously initiated. The connection will then terminate.\
> \
> Any further action on the conversation is only allowed after the connection is terminated.\
> \
> A 200 status code doesn't indicate the successful completion of this endpoint, because the status code is transmitted before the stream starts. At any point during the stream,\
> an \`ErrorEvent\` might be sent, which indicates that an error has occurred. The connection will be immediately closed after.\
> \
> This endpoint can only be called on a conversation that has started but not finished.\
> \
> \#### Permissions\
> This endpoint requires the following permissions:\
> \* \`User:UpdateUserInfo\` on the user who started the conversation.\
> \* \`Conversation:InteractWithConversation\` on the conversation.\
> \
> This endpoint may be impacted by the following permissions:\
> \* \`CurrentAgentActionEvent\`s are only emitted if the authenticated user has the \`Conversation:GetInteractionInsights\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Amigo API","version":"0.1.0"},"servers":[{"url":"https://api.amigo.ai"},{"url":"https://internal-api.amigo.ai"},{"url":"https://api-eu-central-1.amigo.ai"},{"url":"https://api-ap-southeast-2.amigo.ai"},{"url":"https://api-ca-central-1.amigo.ai"}],"security":[{"Bearer-Authorization":[],"Bearer-Authorization-Organization":[],"Basic":[]}],"components":{"securitySchemes":{"Bearer-Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint."}},"schemas":{"UserMessageAudioConfig":{"oneOf":[{"$ref":"#/components/schemas/MP3UserMessageAudioConfig"},{"$ref":"#/components/schemas/PCMUserMessageAudioConfig"}],"discriminator":{"propertyName":"type","mapping":{"mp3":"#/components/schemas/MP3UserMessageAudioConfig","pcm":"#/components/schemas/PCMUserMessageAudioConfig"}}},"MP3UserMessageAudioConfig":{"properties":{"type":{"type":"string","const":"mp3","title":"Type","default":"mp3"}},"type":"object","title":"MP3UserMessageAudioConfig"},"PCMUserMessageAudioConfig":{"properties":{"type":{"type":"string","const":"pcm","title":"Type","default":"pcm"},"frame_rate":{"type":"integer","maximum":44100,"minimum":4000,"title":"Frame Rate"},"n_channels":{"type":"integer","const":1,"title":"N Channels"},"sample_width":{"type":"integer","enum":[2,4],"title":"Sample Width"}},"type":"object","required":["frame_rate","n_channels","sample_width"],"title":"PCMUserMessageAudioConfig"},"src__app__endpoints__conversation__interact_with_conversation__Response":{"anyOf":[{"$ref":"#/components/schemas/ConversationEvent"},{"$ref":"#/components/schemas/UserMessageAvailableEvent"},{"$ref":"#/components/schemas/ErrorEvent"}]},"ConversationEvent":{"anyOf":[{"$ref":"#/components/schemas/InteractionCompleteEvent"},{"$ref":"#/components/schemas/NewMessageEvent"},{"$ref":"#/components/schemas/CurrentAgentActionEvent"}]},"InteractionCompleteEvent":{"properties":{"type":{"type":"string","const":"interaction-complete","title":"Type","default":"interaction-complete"},"message_id":{"type":"string","title":"Message Id","description":"The identifier of the agent message in this interaction."},"interaction_id":{"type":"string","title":"Interaction Id","description":"The identifier of this interaction."},"full_message":{"type":"string","title":"Full Message","description":"A structure containing either the content of the message if it's text, or the transcript of the message if it's audio."},"conversation_completed":{"type":"boolean","title":"Conversation Completed","description":"Whether the conversation is auto-completed after this interaction."}},"type":"object","required":["message_id","interaction_id","full_message","conversation_completed"],"title":"InteractionCompleteEvent","description":"Emitted when the interaction is complete and committed to database. This event is only emitted after all `NewMessageEvent`s are emitted."},"NewMessageEvent":{"properties":{"type":{"type":"string","const":"new-message","title":"Type","default":"new-message"},"message":{"type":"string","title":"Message","description":"Either the raw-text piece or a base-64 encoded string of bytes representing the piece in alternative forms. If it represents audio, the audios are in\nPCM16 format."},"transcript_alignment":{"anyOf":[{"items":{"prefixItems":[{"type":"integer"},{"type":"string"}],"type":"array","maxItems":2,"minItems":2},"type":"array"},{"type":"null"}],"title":"Transcript Alignment","description":"Transcript of the ongoing audio message and how they align with the audio, if the message is in audio format. Otherwise, it's `None`. This is an array of tuples, where each tuple contains\na character and an integer indicating the milliseconds since the audio started when the character is spoken.\n\nNote that this field might not be defined for some events that transmit audio bytes -- in that case, the alignment information for that chunk was already\nincluded in the `transcript_alignment` field in the previous event."},"stop":{"type":"boolean","title":"Stop","description":"Whether this is the last piece of the agent message."},"sequence_number":{"type":"integer","title":"Sequence Number","description":"The sequence number of this piece in the agent message."},"message_id":{"type":"string","title":"Message Id","description":"The identifier of this agent message. "}},"type":"object","required":["message","transcript_alignment","stop","sequence_number","message_id"],"title":"NewMessageEvent","description":"Emitted when a new piece of the agent message is available."},"CurrentAgentActionEvent":{"properties":{"type":{"type":"string","const":"current-agent-action","title":"Type","default":"current-agent-action"},"action":{"$ref":"#/components/schemas/src__app__amigo__service__conversation__Action","description":"The type of action the agent is performing right now."}},"type":"object","required":["action"],"title":"CurrentAgentActionEvent","description":"Emitted when an agent is about to perform an action that aids in the generation of the response. This is emitted before any\n`NewMessageEvent` is emitted."},"src__app__amigo__service__conversation__Action":{"anyOf":[{"$ref":"#/components/schemas/SelectDynamicBehaviorAgentActionEvent"},{"$ref":"#/components/schemas/CheckIfActiveMemoryNeededAgentActionEvent"},{"$ref":"#/components/schemas/ExtractActiveMemoriesAgentActionEvent"},{"$ref":"#/components/schemas/NavigateStateMachineAgentActionEvent"},{"$ref":"#/components/schemas/EngageUserAgentActionEvent"}]},"SelectDynamicBehaviorAgentActionEvent":{"oneOf":[{"$ref":"#/components/schemas/SelectDynamicBehaviorVectorGeneratedEvent"},{"$ref":"#/components/schemas/SelectDynamicBehaviorRelevanceRetrievalCompletedEvent"},{"$ref":"#/components/schemas/SelectDynamicBehaviorCompletedEvent"}],"discriminator":{"propertyName":"type","mapping":{"select-dynamic-behavior-completed":"#/components/schemas/SelectDynamicBehaviorCompletedEvent","select-dynamic-behavior-relevance-retrieval-completed":"#/components/schemas/SelectDynamicBehaviorRelevanceRetrievalCompletedEvent","select-dynamic-behavior-vector-generated":"#/components/schemas/SelectDynamicBehaviorVectorGeneratedEvent"}}},"SelectDynamicBehaviorVectorGeneratedEvent":{"properties":{"type":{"type":"string","const":"select-dynamic-behavior-vector-generated","title":"Type","default":"select-dynamic-behavior-vector-generated"}},"type":"object","title":"SelectDynamicBehaviorVectorGeneratedEvent"},"SelectDynamicBehaviorRelevanceRetrievalCompletedEvent":{"properties":{"type":{"type":"string","const":"select-dynamic-behavior-relevance-retrieval-completed","title":"Type","default":"select-dynamic-behavior-relevance-retrieval-completed"}},"type":"object","title":"SelectDynamicBehaviorRelevanceRetrievalCompletedEvent"},"SelectDynamicBehaviorCompletedEvent":{"properties":{"type":{"type":"string","const":"select-dynamic-behavior-completed","title":"Type","default":"select-dynamic-behavior-completed"},"selected_dynamic_behavior_set_version_info":{"anyOf":[{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2},{"type":"null"}],"title":"Selected Dynamic Behavior Set Version Info"},"previous_selected_dynamic_behavior_set_version_info":{"anyOf":[{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2},{"type":"null"}],"title":"Previous Selected Dynamic Behavior Set Version Info"}},"type":"object","required":["selected_dynamic_behavior_set_version_info","previous_selected_dynamic_behavior_set_version_info"],"title":"SelectDynamicBehaviorCompletedEvent"},"CheckIfActiveMemoryNeededAgentActionEvent":{"properties":{"type":{"type":"string","const":"check-if-active-memory-needed-completed","title":"Type","default":"check-if-active-memory-needed-completed"},"queries":{"items":{"type":"string"},"type":"array","title":"Queries"}},"type":"object","required":["queries"],"title":"CheckIfActiveMemoryNeededCompletedEvent"},"ExtractActiveMemoriesAgentActionEvent":{"properties":{"type":{"type":"string","const":"extract-active-memories-completed","title":"Type","default":"extract-active-memories-completed"},"queries_and_responses":{"items":{"prefixItems":[{"type":"string"},{"type":"string"}],"type":"array","maxItems":2,"minItems":2},"type":"array","title":"Queries And Responses"}},"type":"object","required":["queries_and_responses"],"title":"ExtractActiveMemoriesCompletedEvent"},"NavigateStateMachineAgentActionEvent":{"anyOf":[{"$ref":"#/components/schemas/NavigateStateMachineDynamicBehaviorOverrideEvent"},{"$ref":"#/components/schemas/NavigateStateMachineActionStateActionSelectedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineDecisionStateDecisionStartedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineExitConditionSelectedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineRecallStateDynamicQueriesGeneratedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineRecallStateStaticQueriesRetrievedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineRecallStateActiveMemoryRetrievedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineReflectionStatePromptRetrievedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineReflectionStateReflectionGeneratedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineAnnotationStateAnnotationRetrievedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineStateTransitionedEvent"},{"$ref":"#/components/schemas/GenerateToolParamsEvent"},{"$ref":"#/components/schemas/NavigateStateMachineToolCallStateToolOutputAvailableEvent"},{"$ref":"#/components/schemas/ToolCallStartedEvent"},{"$ref":"#/components/schemas/ToolCallEndedEvent"},{"$ref":"#/components/schemas/ActionTooLongEvent"}]},"NavigateStateMachineDynamicBehaviorOverrideEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-dynamic-behavior-override","title":"Type","default":"navigate-state-machine-dynamic-behavior-override"},"overriding_instructions":{"type":"boolean","title":"Overriding Instructions","description":"Whether the dynamic behavior set is overriding instructions during this interaction."},"overriding_tool_candidates":{"type":"boolean","title":"Overriding Tool Candidates","description":"Whether the dynamic behavior set is overriding the tool candidates during this interaction."}},"type":"object","required":["overriding_instructions","overriding_tool_candidates"],"title":"NavigateStateMachineDynamicBehaviorOverrideEvent","description":"Indicating that the agent has merged the dynamic behavior set's instructions with the instructions from the current state."},"NavigateStateMachineActionStateActionSelectedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-action-state-action-selected","title":"Type","default":"navigate-state-machine-action-state-action-selected"},"action":{"type":"string","title":"Action"}},"type":"object","required":["action"],"title":"NavigateStateMachineActionStateActionSelectedEvent","description":"Indicating that the agent has selected an action from the current state."},"NavigateStateMachineDecisionStateDecisionStartedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-decision-state-decision-started","title":"Type","default":"navigate-state-machine-decision-state-decision-started"}},"type":"object","title":"NavigateStateMachineDecisionStateDecisionStartedEvent","description":"Indicating that the agent has started making a decision in the current decision state."},"NavigateStateMachineExitConditionSelectedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-exit-condition-selected","title":"Type","default":"navigate-state-machine-exit-condition-selected"},"exit_condition":{"type":"string","title":"Exit Condition","description":"The exit condition that the agent has selected."},"next_state_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next State State Machine Version Info","description":"The state machine version info of the next state."},"next_state_name":{"type":"string","title":"Next State Name","description":"The name of the next state."}},"type":"object","required":["exit_condition","next_state_state_machine_version_info","next_state_name"],"title":"NavigateStateMachineExitConditionSelectedEvent","description":"Indicating that the agent has selected an exit condition from the current action or decision state."},"NavigateStateMachineRecallStateDynamicQueriesGeneratedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-recall-state-dynamic-queries-generated","title":"Type","default":"navigate-state-machine-recall-state-dynamic-queries-generated"},"dynamic_queries":{"items":{"type":"string"},"type":"array","title":"Dynamic Queries","description":"The dynamic queries that the agent has generated."},"requested_information":{"type":"string","title":"Requested Information","description":"The information that the agent needs from the queries."}},"type":"object","required":["dynamic_queries","requested_information"],"title":"NavigateStateMachineRecallStateDynamicQueriesGeneratedEvent","description":"Indicating that the agent has generated dynamic queries in the current the recall state."},"NavigateStateMachineRecallStateStaticQueriesRetrievedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-recall-state-static-queries-retrieved","title":"Type","default":"navigate-state-machine-recall-state-static-queries-retrieved"},"static_queries":{"items":{"type":"string"},"type":"array","title":"Static Queries","description":"The static queries that the agent has retrieved."}},"type":"object","required":["static_queries"],"title":"NavigateStateMachineRecallStateStaticQueriesRetrievedEvent","description":"Indicating that the agent has retrieved the static queries in the current the recall state."},"NavigateStateMachineRecallStateActiveMemoryRetrievedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-recall-state-active-memory-retrieved","title":"Type","default":"navigate-state-machine-recall-state-active-memory-retrieved"},"queries_and_responses":{"items":{"prefixItems":[{"type":"string"},{"type":"string"}],"type":"array","maxItems":2,"minItems":2},"type":"array","title":"Queries And Responses","description":"A list of tuples of queries and responses."}},"type":"object","required":["queries_and_responses"],"title":"NavigateStateMachineRecallStateActiveMemoryRetrievedEvent","description":"Indicating that the agent has retrieved the active memory in the current the recall state."},"NavigateStateMachineReflectionStatePromptRetrievedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-reflection-state-prompt-retrieved","title":"Type","default":"navigate-state-machine-reflection-state-prompt-retrieved"},"prompt":{"type":"string","title":"Prompt"}},"type":"object","required":["prompt"],"title":"NavigateStateMachineReflectionStatePromptRetrievedEvent","description":"Indicating that the agent has retrieved the prompt in the current reflection state."},"NavigateStateMachineReflectionStateReflectionGeneratedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-reflection-state-reflection-generated","title":"Type","default":"navigate-state-machine-reflection-state-reflection-generated"},"reflection":{"type":"string","title":"Reflection","description":"The reflection that the agent has generated."}},"type":"object","required":["reflection"],"title":"NavigateStateMachineReflectionStateReflectionGeneratedEvent","description":"Indicating that the agent has generated the reflection in the current reflection state."},"NavigateStateMachineAnnotationStateAnnotationRetrievedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-annotation-state-annotation-retrieved","title":"Type","default":"navigate-state-machine-annotation-state-annotation-retrieved"},"annotation":{"type":"string","title":"Annotation"}},"type":"object","required":["annotation"],"title":"NavigateStateMachineAnnotationStateAnnotationRetrievedEvent","description":"Indicating that the agent has retrieved the annotation in the current annotation state."},"NavigateStateMachineStateTransitionedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-state-transitioned","title":"Type","default":"navigate-state-machine-state-transitioned"},"prev_state":{"type":"string","title":"Prev State","description":"The previous state."},"prev_state_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Prev State State Machine Version Info","description":"The state machine version info of the previous state."},"next_state":{"type":"string","title":"Next State","description":"The next state."},"next_state_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next State State Machine Version Info","description":"The state machine version info of the next state."}},"type":"object","required":["prev_state","prev_state_state_machine_version_info","next_state","next_state_state_machine_version_info"],"title":"NavigateStateMachineStateTransitionedEvent","description":"Indicating that the agent has transitioned to a new state."},"GenerateToolParamsEvent":{"anyOf":[{"$ref":"#/components/schemas/GenerateToolParamsDesignatedToolRetrievedEvent"},{"$ref":"#/components/schemas/GenerateToolParamsDesignatedToolCallParamsGeneratedEvent"},{"$ref":"#/components/schemas/ActionTooLongEvent"},{"$ref":"#/components/schemas/ToolCallStartedEvent"},{"$ref":"#/components/schemas/ToolCallEndedEvent"}]},"GenerateToolParamsDesignatedToolRetrievedEvent":{"properties":{"type":{"type":"string","const":"designated-tool-retrieved","title":"Type","default":"designated-tool-retrieved"},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."}},"type":"object","required":["tool_id","tool_version"],"title":"GenerateToolParamsDesignatedToolRetrievedEvent"},"GenerateToolParamsDesignatedToolCallParamsGeneratedEvent":{"properties":{"type":{"type":"string","const":"designated-tool-call-params-generated","title":"Type","default":"designated-tool-call-params-generated"},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."},"tool_call_params":{"additionalProperties":true,"type":"object","title":"Tool Call Params","description":"The generated tool call parameters."}},"type":"object","required":["tool_id","tool_version","tool_call_params"],"title":"GenerateToolParamsDesignatedToolCallParamsGeneratedEvent"},"ActionTooLongEvent":{"properties":{"type":{"type":"string","const":"action-too-long","title":"Type","default":"action-too-long"},"filler":{"type":"string","title":"Filler","description":"A filler that can be played while waiting for the action to complete. If the audio filler exists, this is monochannel, 16-bit PCM WAV audio (at sample rate 16kHz) encoded in base64 encoding.\nOtherwise, this is the text corresponding to the audio filler."},"previously_started_event":{"title":"Previously Started Event","description":"The previously started event that is taking too long."}},"type":"object","required":["filler","previously_started_event"],"title":"ActionTooLongEvent","description":"Indicating that a previously-started action of the agent is taking too long. This event supplies a filler text that can be displayed\nwhile waiting for the action to complete."},"ToolCallStartedEvent":{"properties":{"type":{"type":"string","const":"tool-call-started","title":"Type","default":"tool-call-started"},"tool_round_index":{"type":"integer","title":"Tool Round Index","description":"Within the current LLM interaction, the round of tool call."},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."},"input_params":{"additionalProperties":true,"type":"object","title":"Input Params","description":"The input parameters for the tool call."}},"type":"object","required":["tool_round_index","tool_id","tool_version","input_params"],"title":"ToolCallStartedEvent","description":"Indicating that the agent has started executing a tool."},"ToolCallEndedEvent":{"properties":{"type":{"type":"string","const":"tool-call-ended","title":"Type","default":"tool-call-ended"},"tool_round_index":{"type":"integer","title":"Tool Round Index","description":"Within the current LLM interaction, the round of tool call."},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."},"input_parameters":{"additionalProperties":true,"type":"object","title":"Input Parameters","description":"The input parameters for the tool call."},"result":{"type":"string","title":"Result","description":"The result of the tool call."},"duration":{"type":"number","title":"Duration","description":"The duration of the tool call in seconds."}},"type":"object","required":["tool_round_index","tool_id","tool_version","input_parameters","result","duration"],"title":"ToolCallEndedEvent","description":"Indicating that the agent has finished executing a tool."},"NavigateStateMachineToolCallStateToolOutputAvailableEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-tool-call-state-tool-output-available","title":"Type","default":"navigate-state-machine-tool-call-state-tool-output-available"},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."},"tool_output":{"type":"string","title":"Tool Output","description":"The tool output."},"duration":{"type":"number","title":"Duration","description":"The duration taken to receive the tool output in seconds."},"input_arguments":{"additionalProperties":true,"type":"object","title":"Input Arguments","description":"The input arguments used for the tool call."}},"type":"object","required":["tool_id","tool_version","tool_output","duration","input_arguments"],"title":"NavigateStateMachineToolCallStateToolOutputAvailableEvent","description":"Indicating that the agent has received the tool output in the current tool call state."},"EngageUserAgentActionEvent":{"oneOf":[{"$ref":"#/components/schemas/EngageUserDynamicBehaviorOverrideEvent"},{"$ref":"#/components/schemas/EngageUserMessageFragmentGeneratedEvent"},{"$ref":"#/components/schemas/ToolCallStartedEvent"},{"$ref":"#/components/schemas/ToolCallEndedEvent"},{"$ref":"#/components/schemas/ActionTooLongEvent"}],"discriminator":{"propertyName":"type","mapping":{"action-too-long":"#/components/schemas/ActionTooLongEvent","engage-user-dynamic-behavior-override":"#/components/schemas/EngageUserDynamicBehaviorOverrideEvent","engage-user-message-fragment-generated":"#/components/schemas/EngageUserMessageFragmentGeneratedEvent","tool-call-ended":"#/components/schemas/ToolCallEndedEvent","tool-call-started":"#/components/schemas/ToolCallStartedEvent"}}},"EngageUserDynamicBehaviorOverrideEvent":{"properties":{"type":{"type":"string","const":"engage-user-dynamic-behavior-override","title":"Type","default":"engage-user-dynamic-behavior-override"},"overriding_instructions":{"type":"boolean","title":"Overriding Instructions","description":"Whether the dynamic behavior set is overriding instructions during this interaction."},"overriding_tool_candidates":{"type":"boolean","title":"Overriding Tool Candidates","description":"Whether the dynamic behavior set is overriding the tool candidates during this interaction."}},"type":"object","required":["overriding_instructions","overriding_tool_candidates"],"title":"EngageUserDynamicBehaviorOverrideEvent","description":"Indicating that the agent has merged the dynamic behavior set's instructions with the instructions from the current state."},"EngageUserMessageFragmentGeneratedEvent":{"properties":{"type":{"type":"string","const":"engage-user-message-fragment-generated","title":"Type","default":"engage-user-message-fragment-generated"},"index":{"type":"integer","title":"Index","description":"The index of the fragment in the agent response."},"fragment":{"type":"string","title":"Fragment","description":"The fragment of the agent response that has been generated."},"is_final":{"type":"boolean","title":"Is Final","description":"Whether this fragment is the final fragment of the agent response."}},"type":"object","required":["index","fragment","is_final"],"title":"EngageUserMessageFragmentGeneratedEvent","description":"Indicating that the agent has generated a fragment of the agent response."},"UserMessageAvailableEvent":{"properties":{"type":{"type":"string","const":"user-message-available","title":"Type","default":"user-message-available"},"message_id":{"type":"string","title":"Message Id","description":"The identifier of the user message."},"user_message":{"type":"string","title":"User Message","description":"The text of the user message."}},"type":"object","required":["message_id","user_message"],"title":"UserMessageAvailableEvent","description":"Emitted when the full text of the user message is available. In particular, for voice messages, this event is emitted when the transcription of the user message is complete. It's the first event in the response stream."},"ErrorEvent":{"properties":{"type":{"type":"string","const":"error","title":"Type","default":"error"},"http_error_code":{"type":"integer","title":"Http Error Code","description":"The HTTP status code of the error."},"error_description":{"type":"string","title":"Error Description","description":"A description of the error."}},"type":"object","required":["http_error_code","error_description"],"title":"ErrorEvent","description":"Emitted when there is an error during the stream. This event could be emitted even if the request returns with a 200.\nIf received before an `interaction-complete` event, the client should consider the entire interaction void and retry. If received after,\nthen the conversation has completed and an error occurred during the post-processing, so the client should consider the interaction valid and saved,\nbut manually call the `FinishConversation` endpoint to retry the post-processing."}}},"paths":{"/v1/{organization}/conversation/{conversation_id}/interact":{"post":{"tags":["Conversation"],"summary":"Interact with a conversation","description":"Send a new user message to the conversation. The endpoint will perform analysis and generate an agent message in response.\n\nA `UserMessageAvailableEvent` will be the first event in the response, which includes the user message if it's sent as text, or the transcribed message if it's sent as voice.\nA series of `CurrentAgentActionEvent`s will follow, which indicates steps in the agent's thinking process. Then the agent message is generated sequentially in pieces, with each piece\nbeing sent as a `NewMessageEvent` in the response. After all the pieces are sent, an `InteractionCompleteEvent` is sent. Depending on the `conversation_completed` property in this event, the conversation will be awaiting\na new message from the user, or it might automatically end (for instance, because the user message indicates the user wants to end the session), while the conversation is marked as finished and the post-conversation\nanalysis asynchronously initiated. The connection will then terminate.\n\nAny further action on the conversation is only allowed after the connection is terminated.\n\nA 200 status code doesn't indicate the successful completion of this endpoint, because the status code is transmitted before the stream starts. At any point during the stream,\nan `ErrorEvent` might be sent, which indicates that an error has occurred. The connection will be immediately closed after.\n\nThis endpoint can only be called on a conversation that has started but not finished.\n\n#### Permissions\nThis endpoint requires the following permissions:\n* `User:UpdateUserInfo` on the user who started the conversation.\n* `Conversation:InteractWithConversation` on the conversation.\n\nThis endpoint may be impacted by the following permissions:\n* `CurrentAgentActionEvent`s are only emitted if the authenticated user has the `Conversation:GetInteractionInsights` permission.","operationId":"interact-with-conversation","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"The identifier of the conversation to send a message to.","title":"Conversation Id"},"description":"The identifier of the conversation to send a message to."},{"name":"organization","in":"path","required":true,"schema":{"type":"string","title":"Organization"}},{"name":"request_format","in":"query","required":true,"schema":{"enum":["text","voice"],"type":"string","description":"The format in which the user message is delivered to the server.","title":"Request Format"},"description":"The format in which the user message is delivered to the server."},{"name":"response_format","in":"query","required":true,"schema":{"enum":["text","voice"],"type":"string","description":"The format of the response that will be sent to the user.","title":"Response Format"},"description":"The format of the response that will be sent to the user."},{"name":"current_agent_action_type","in":"query","required":false,"schema":{"type":"string","description":"A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`.","default":"^.*$","title":"Current Agent Action Type"},"description":"A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`."},{"name":"request_audio_config","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/UserMessageAudioConfig"},{"type":"null"}],"description":"Configuration for the user message audio. This is only required if `request_format` is set to `voice`.","title":"Request Audio Config"},"description":"Configuration for the user message audio. This is only required if `request_format` is set to `voice`."},{"name":"content-type","in":"header","required":true,"schema":{"type":"string","pattern":"^multipart\\/form-data; boundary=.+$","description":"The content type of the request body, which must be `multipart/form-data` followed by a boundary.","title":"Content-Type"},"description":"The content type of the request body, which must be `multipart/form-data` followed by a boundary."},{"name":"x-mongo-cluster-name","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.","title":"X-Mongo-Cluster-Name"},"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database."},{"name":"Sec-WebSocket-Protocol","in":"header","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Sec-Websocket-Protocol"}}],"responses":{"200":{"description":"\nSucceeded. The response will be a stream of events in JSON format separated by newlines. The server will transmit an event as soon as one is available,\nso the client should respond to the events as soon as one arrives, and keep listening until the server closes the connection.\n","content":{"application/x-ndjson":{"schema":{"type":"object","$ref":"#/components/schemas/src__app__endpoints__conversation__interact_with_conversation__Response"}}}},"400":{"description":"\nThis may occur for the following reasons:\n* The user message is empty.\n* The preferred language does not support voice transcription or response.\n* The `response_audio_format` field is not set when voice output is requested.\n* The timestamps for external event messages are not in the past.\n* The timestamps for external event messages are inconsistent with the conversation.\n* The agent does not have voice config specified."},"401":{"description":"Invalid authorization credentials."},"403":{"description":"Missing required permissions."},"404":{"description":"Specified organization or conversation is not found."},"408":{"description":"The request body stream timed out."},"409":{"description":"The specified conversation is already finished, or a related operation is in process."},"415":{"description":"The format of the supplied audio file is not supported."},"422":{"description":"Invalid request path parameter or request body failed validation."},"429":{"description":"The user has exceeded the rate limit of 15 requests per minute for this endpoint."},"503":{"description":"The service is going through temporary maintenance."}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"oneOf":[{"properties":{"initial_message_type":{"const":"external-event","title":"Initial Message Type","type":"string"},"recorded_message":{"minLength":1,"type":"string"},"external_event_message_content":{"default":[],"description":"The contents of external event messages to be inserted before the initial message, in chronological order.","items":{"minLength":1,"type":"string"},"title":"External Event Message Content","type":"array"},"external_event_message_timestamp":{"default":[],"description":"The timestamps of external event messages to be inserted before the initial message, in chronological order.","items":{"format":"date-time","type":"string"},"title":"External Event Message Timestamp","type":"array"}},"required":["initial_message_type","recorded_message"],"title":"ExternalEventClientMessageRequestBody","type":"object"},{"properties":{"initial_message_type":{"const":"user-message","title":"Initial Message Type","type":"string"},"recorded_message":{"minLength":1,"type":"string"},"external_event_message_content":{"default":[],"description":"The contents of external event messages to be inserted before the initial message, in chronological order.","items":{"minLength":1,"type":"string"},"title":"External Event Message Content","type":"array"},"external_event_message_timestamp":{"default":[],"description":"The timestamps of external event messages to be inserted before the initial message, in chronological order.","items":{"format":"date-time","type":"string"},"title":"External Event Message Timestamp","type":"array"}},"required":["initial_message_type","recorded_message"],"title":"UserMessageClientMessageRequestBody","type":"object"},{"properties":{"initial_message_type":{"const":"skip","title":"Initial Message Type","type":"string"},"recorded_message":{"description":"The body of the initial message, which must be empty.","maxLength":0,"title":"Recorded Message","type":"string"},"external_event_message_content":{"default":[],"description":"Must be empty, as external event messages cannot be sent with skips.","items":{"minLength":1,"type":"string"},"maxItems":0,"title":"External Event Message Content","type":"array"},"external_event_message_timestamp":{"default":[],"description":"Must be empty, as external event messages cannot be sent with skips.","items":{"format":"date-time","type":"string"},"maxItems":0,"title":"External Event Message Timestamp","type":"array"}},"required":["initial_message_type","recorded_message"],"title":"SkipClientMessageRequestBody","type":"object"}]}}}}}}}}
```

## Retrieve message source

> Retrieve the raw source of the given message. It's only applicable to messages that did not originate as texts.\
> \
> \#### Permissions\
> This endpoint requires the following permissions:\
> \* \`Conversation:GetMessage\` on the the message.

```json
{"openapi":"3.1.0","info":{"title":"Amigo API","version":"0.1.0"},"servers":[{"url":"https://api.amigo.ai"},{"url":"https://internal-api.amigo.ai"},{"url":"https://api-eu-central-1.amigo.ai"},{"url":"https://api-ap-southeast-2.amigo.ai"},{"url":"https://api-ca-central-1.amigo.ai"}],"security":[{"Bearer-Authorization":[],"Bearer-Authorization-Organization":[],"Basic":[]}],"components":{"securitySchemes":{"Bearer-Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint."}}},"paths":{"/v1/{organization}/conversation/{conversation_id}/messages/{message_id}/source":{"get":{"tags":["Conversation"],"summary":"Retrieve message source","description":"Retrieve the raw source of the given message. It's only applicable to messages that did not originate as texts.\n\n#### Permissions\nThis endpoint requires the following permissions:\n* `Conversation:GetMessage` on the the message.","operationId":"retrieve-message-source","parameters":[{"name":"organization","in":"path","required":true,"schema":{"type":"string","title":"Organization"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"The identifier of the conversation.","title":"Conversation Id"},"description":"The identifier of the conversation."},{"name":"message_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"The identifier of the message.","title":"Message Id"},"description":"The identifier of the message."},{"name":"long_lived","in":"query","required":false,"schema":{"type":"boolean","description":"Whether to generate a long-lived URL which lasts 12 hours. For security purposes, it's recommended to set this to false as much as possible.","default":false,"title":"Long Lived"},"description":"Whether to generate a long-lived URL which lasts 12 hours. For security purposes, it's recommended to set this to false as much as possible."},{"name":"x-mongo-cluster-name","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.","title":"X-Mongo-Cluster-Name"},"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database."},{"name":"Sec-WebSocket-Protocol","in":"header","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Sec-Websocket-Protocol"}}],"responses":{"200":{"description":"Succeeded.","content":{"application/json":{"schema":{}}}},"400":{"description":"The message is a text message."},"401":{"description":"Invalid authorization credentials."},"403":{"description":"Missing required permissions."},"404":{"description":"Specified organization or message is not found."},"422":{"description":"Invalid request path parameter failed validation."},"429":{"description":"The user has exceeded the rate limit of 30 request per minute for this endpoint."},"503":{"description":"The service is going through temporary maintenance."}}}}}}
```

## Generate conversation starters for a service

> Generate conversation starters for a service.\
> \
> \#### Permissions\
> This endpoint requires the following permissions:\
> \* \`Conversation:CreateConversation\` for a hypothetical new conversation created using the same setting.

```json
{"openapi":"3.1.0","info":{"title":"Amigo API","version":"0.1.0"},"servers":[{"url":"https://api.amigo.ai"},{"url":"https://internal-api.amigo.ai"},{"url":"https://api-eu-central-1.amigo.ai"},{"url":"https://api-ap-southeast-2.amigo.ai"},{"url":"https://api-ca-central-1.amigo.ai"}],"security":[{"Bearer-Authorization":[],"Bearer-Authorization-Organization":[],"Basic":[]}],"components":{"securitySchemes":{"Bearer-Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint."}},"schemas":{"src__app__endpoints__conversation__generate_conversation_starter__Request":{"properties":{"service_id":{"type":"string","pattern":"^[a-f0-9]{24}$","title":"Service Id","description":"The identifier of the service to create a conversation starter for."},"service_version_set_name":{"type":"string","title":"Service Version Set Name","description":"The version set of the service to use. If not provided, the `release` version set is used.","default":"release"},"facets":{"items":{"$ref":"#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__1"},"type":"array","minItems":1,"title":"Facets","description":"The facets that the generated conversation starter should be about. Each generated starter is related to some of these facets."},"min_count":{"type":"integer","maximum":10,"exclusiveMinimum":0,"title":"Min Count","description":"The minimum (inclusive) number of conversation starters to generate."},"max_count":{"type":"integer","maximum":10,"exclusiveMinimum":0,"title":"Max Count","description":"The maximum (inclusive) number of conversation starters to generate."},"generation_instructions":{"$ref":"#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__1","description":"The instruction for the conversation starter generation."}},"type":"object","required":["service_id","facets","min_count","max_count","generation_instructions"],"title":"Request"},"amigo_lib__pydantic__base_model__StrippedNonemptyString__1":{"type":"string","minLength":1},"src__app__endpoints__conversation__generate_conversation_starter__Response":{"properties":{"prompts":{"items":{"$ref":"#/components/schemas/Prompt"},"type":"array","title":"Prompts","description":"The generated prompts."}},"type":"object","required":["prompts"],"title":"Response"},"Prompt":{"properties":{"prompt":{"type":"string","title":"Prompt","description":"The generated prompt."},"facets":{"items":{"type":"string"},"type":"array","title":"Facets","description":"The facets that the generated prompt is about."}},"type":"object","required":["prompt","facets"],"title":"Prompt"}}},"paths":{"/v1/{organization}/conversation/conversation_starter":{"post":{"tags":["Conversation"],"summary":"Generate conversation starters for a service","description":"Generate conversation starters for a service.\n\n#### Permissions\nThis endpoint requires the following permissions:\n* `Conversation:CreateConversation` for a hypothetical new conversation created using the same setting.","operationId":"generate-conversation-starter","parameters":[{"name":"organization","in":"path","required":true,"schema":{"type":"string","title":"Organization"}},{"name":"x-mongo-cluster-name","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.","title":"X-Mongo-Cluster-Name"},"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database."},{"name":"Sec-WebSocket-Protocol","in":"header","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Sec-Websocket-Protocol"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__app__endpoints__conversation__generate_conversation_starter__Request"}}}},"responses":{"200":{"description":"Succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__app__endpoints__conversation__generate_conversation_starter__Response"}}}},"401":{"description":"Invalid authorization credentials."},"403":{"description":"Missing required permissions."},"404":{"description":"Service not found."},"422":{"description":"Invalid request path parameter or request body failed validation."},"429":{"description":"The user has exceeded the rate limit of 10 requests per minute for this endpoint."},"503":{"description":"The service is going through temporary maintenance."}}}}}}
```

## Modify tags of a conversation

> Modify the tags of a conversation.\
> \
> \#### Permissions\
> This endpoint requires the following permissions:\
> \* \`Conversation:ModifyConversation\` for the conversation to modify tags for.

```json
{"openapi":"3.1.0","info":{"title":"Amigo API","version":"0.1.0"},"servers":[{"url":"https://api.amigo.ai"},{"url":"https://internal-api.amigo.ai"},{"url":"https://api-eu-central-1.amigo.ai"},{"url":"https://api-ap-southeast-2.amigo.ai"},{"url":"https://api-ca-central-1.amigo.ai"}],"security":[{"Bearer-Authorization":[],"Bearer-Authorization-Organization":[],"Basic":[]}],"components":{"securitySchemes":{"Bearer-Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint."}},"schemas":{"src__app__endpoints__conversation__modify_tags_of_conversation__Request":{"properties":{"updates":{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/StrippedNonemptyString___w__s_____"},{"type":"null"}]},"propertyNames":{"$ref":"#/components/schemas/StrippedNonemptyString___w__s_____"},"type":"object","maxProperties":20,"title":"Updates","description":"A mapping of tags to add or update on the conversation. Existing tags not included here remain unchanged.","default":{}},"deletes":{"items":{"$ref":"#/components/schemas/amigo_lib__pydantic__base_model__StrippedNonemptyString__1"},"type":"array","uniqueItems":true,"title":"Deletes","description":"A list of tags to remove from the conversation.","default":[]}},"type":"object","title":"Request"},"StrippedNonemptyString___w__s_____":{"type":"string","minLength":1,"pattern":"^[\\w\\s]+$"},"amigo_lib__pydantic__base_model__StrippedNonemptyString__1":{"type":"string","minLength":1}}},"paths":{"/v1/{organization}/conversation/{conversation_id}/tags/":{"post":{"tags":["Conversation"],"summary":"Modify tags of a conversation","description":"Modify the tags of a conversation.\n\n#### Permissions\nThis endpoint requires the following permissions:\n* `Conversation:ModifyConversation` for the conversation to modify tags for.","operationId":"modify-tags-of-conversation","parameters":[{"name":"organization","in":"path","required":true,"schema":{"type":"string","title":"Organization"}},{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$","title":"Conversation Id"}},{"name":"x-mongo-cluster-name","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.","title":"X-Mongo-Cluster-Name"},"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database."},{"name":"Sec-WebSocket-Protocol","in":"header","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Sec-Websocket-Protocol"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__app__endpoints__conversation__modify_tags_of_conversation__Request"}}}},"responses":{"204":{"description":"Succeeded."},"400":{"description":"The conversation cannot contain more than 20 tags."},"401":{"description":"Invalid authorization credentials."},"403":{"description":"Missing required permissions."},"404":{"description":"Specified organization or conversation is not found."},"422":{"description":"Invalid request path parameter or request body failed validation."},"429":{"description":"The user has exceeded the rate limit of 50 requests per minute for this endpoint."},"503":{"description":"The service is going through temporary maintenance."}}}}}}
```