{"openapi":"3.0.1","info":{"title":"Exchange Event","version":"1.0"},"servers":[{"url":"/"}],"paths":{"/api/conversation/v1/exchange-events/sse":{"post":{"description":"Sends ExchangeEventSSEData messages as data-only server-sent events (SSE).","operationId":"ExchangeEvent_CreateExchangeEventSSE","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CreateExchangeEventRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ExchangeEventSSEData"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}},"description":"An unexpected error response."}},"summary":"Create Exchange Event SSE Service","tags":["ExchangeEvent"],"x-codegen-request-body-name":"body"}}},"components":{"schemas":{"ExchangeInputAdditionalQuestionRequest":{"description":"Specifies whether to include related questions in the response.\n\n - UNSPECIFIED: Default option, none requested.\n - RELATED: Request only related questions.\n - FOLLOWUP: Request only follow-up questions.\n - RELATED_AND_FOLLOWUP: Request both related and follow-up questions.","type":"string"},"protobufAny":{"description":"`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n    Foo foo = ...;\n    Any any;\n    any.PackFrom(foo);\n    ...\n    if (any.UnpackTo(&foo)) {\n      ...\n    }\n\nExample 2: Pack and unpack a message in Java.\n\n    Foo foo = ...;\n    Any any = Any.pack(foo);\n    ...\n    if (any.is(Foo.class)) {\n      foo = any.unpack(Foo.class);\n    }\n\nExample 3: Pack and unpack a message in Python.\n\n    foo = Foo(...)\n    any = Any()\n    any.Pack(foo)\n    ...\n    if any.Is(Foo.DESCRIPTOR):\n      any.Unpack(foo)\n      ...\n\nExample 4: Pack and unpack a message in Go\n\n     foo := &pb.Foo{...}\n     any, err := anypb.New(foo)\n     if err != nil {\n       ...\n     }\n     ...\n     foo := &pb.Foo{}\n     if err := any.UnmarshalTo(foo); err != nil {\n       ...\n     }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\n\nJSON\n\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n    package google.profile;\n    message Person {\n      string first_name = 1;\n      string last_name = 2;\n    }\n\n    {\n      \"@type\": \"type.googleapis.com/google.profile.Person\",\n      \"firstName\": <string>,\n      \"lastName\": <string>\n    }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n    {\n      \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n      \"value\": \"1.212s\"\n    }","properties":{"type_url":{"description":"Uniquely identifies the type of the serialized protocol buffer message; the last segment of the path represents the fully qualified name of the type, for example, `path/google.protobuf.Duration`.","type":"string"},"value":{"description":"The valid serialized protocol buffer of the type_url.","format":"byte","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$","type":"string"}},"type":"object"},"protobufNullValue":{"default":"NULL_VALUE","description":"`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\n The JSON representation for `NullValue` is JSON `null`.\n\n - NULL_VALUE: Null value.","enum":["NULL_VALUE"],"type":"string"},"rpcStatus":{"description":"Defines a logical error model; contains error code, error message, and error details.","properties":{"code":{"description":"An enum value of google.rpc.Code.","format":"int32","type":"integer"},"message":{"description":"Developer-facing error message.","type":"string"},"details":{"description":"List of messages that carry the error details.","items":{"$ref":"#/components/schemas/protobufAny"},"type":"array"}},"type":"object"},"v1Attachment":{"properties":{"content_type":{"description":"The content type of the additional information. Format of each type field is application/vnd.pryon.**{content_type}**. Commonly occurring types are:\n- **text** - The answer snippet or the text corresponding to detected short spans within the answer_in_context. Best_n will be the same string as the ‘text’ field and represents the ranking of the sentence within the AIC/chunk.\n- **answer_in_context** - Chunk of text identified as most relevant to the input query. The smaller text answer/reply is extracted from this larger text.\n- **answer_type** - Answer type or classification. Answer types include:\n   - **TEXT_EXCERPT**: Default.\n   - **FAQ**: An answer derived from the frequently asked questions.\n   - **OUT_OF_DOMAIN**: A query that is out of domain.\n   - **NON_ASCII_OUT_OF_SCOPE**: A query that is out of scope due to non ascii characters.\n   - **BELOW_THRESHOLD**: The best answer scored below the minimum specified score.\n   - **NO_ANSWER**: No suitably scored answer was found.\n- **answer_approval_id** - Approval ID of matching verified answer - valid UUID v4 string.\n- **score** - An approximation of the strength of the returned answer and answer_in_context chunk, or the float score returned from a model.\n- **level** - Configurable answer confidence levels to categorize outputs.\n- **content_id** - content_id of the knowledge domain content where the answer is located. A client application may use the content API to get more information about the content.\n- **content_display_name** - Display name of the source file that includes the best sentence answer.\n- **content_source_location** - URL of the source content where the answer and chunk are located.\n- **index** - Index into a custom data source.\n- **followup_choice** - Indicates a multiple-choice question is being returned to the user as a reply to their request.  Each of the choices will be an attachment with this value.\n- **related_questions** - Questions related to the input question. e.g. key: rq_best_<ix>, value: {content_type:application/vnd.pryon.related_questions, content: <string>}, where ix is the index from 1 onwards.\n- **related_questions_score** - Score of a Related Question, e.g. key: rq_score_best_<ix>, value: {content_type:application/vnd.pryon.related_questions_score, content: <string>}, where ix is the index from 1 onwards.\n- **followup_questions** - Followup Question to the input question. e.g. key: fq_best_<ix>, value: {content_type:application/vnd.pryon.followup_questions, content: <string>}, where ix is the index from 1 onwards.\n- **followup_questions_score** - Followup Question score. e.g. key: fq_score_best_<ix>, value: {content_type:application/vnd.pryon.followup_questions_score, content: <string>}.\n- **start_page** - Page number where the answer_in_context or the chunk starts in a PDF.\n- **start_page_bbox** - Bounding box of the entire page on which the answer is found.\n- **end_page** - Page number where the answer_in_context ends in a PDF.\n- **start_char_index** - Index of the first occurrence of the best_sentence or answer substring within the surrounding answer_in_context chunk.\n- **end_char_index** - Index of the last occurrence of the best_sentence or answer substring within the surrounding answer_in_context chunk.\n- **bbox** - Bounding box coordinates returned as a list of four floating point numbers representing the top-left and bottom-right corners of the box for the answer snippet on the source document image.\n- **flag** - Boolean flag with either true or false values.\n- **texttrack_cue** - relative time offset from the beginning of the video associated with the short answer. e.g. key: \"texttrack_cue\", value: {content_type: application/vnd.pryon.texttrack_cue, content: <HH:MM:SS>}.","type":"string"},"content":{"description":"The content of the additional information.","type":"string"}},"type":"object"},"v1Context":{"description":"Additional context for this output.","properties":{"augmentation":{"description":"Predefined additional information provided with the source of this output.","properties":{},"type":"object"}},"type":"object"},"v1CreateExchangeEventRequest":{"description":"CreateExchangeEventRequest represents a request to create a new exchange event.","properties":{"input":{"$ref":"#/components/schemas/v1ExchangeInput"},"conversation_context":{"description":"Context of the conversation used to enhance the generative response; modifying a conversation context string from previous responses returns an error.","type":"string"},"randomness":{"description":"Randomness of the generated text, ranging from 0 to 1; default is 0. Higher values result in more random text; lower values produce more focused and deterministic text.","format":"float","type":"number"},"max_answer_in_contexts_num":{"description":"Maximum number of contextual responses considered when generating a response; default is 3.","format":"int32","type":"integer"},"min_answer_in_contexts_score":{"description":"Minimum score of contextual responses considered when generating a response. Must be between 0 and 1; default is 0.55.","format":"float","type":"number"},"answer_in_contexts_beam_delta_cutoff":{"description":"Maximum allowable score difference from the highest score for contextual responses considered when generating a response. Must be between 0 and 1; default is 0.1.","format":"float","type":"number"},"verified_answer_score_threshold":{"description":"Minimum score allowed for a verified answer to be considered as a final answer. Must be between 0 and 1; default is 0.55.","format":"float","type":"number"},"out_of_domain_score_threshold":{"description":"Minimum score allowed for the best answer score for the out of domain message returned as a final answer. Must be between 0 and 1; default is 0.55.","format":"float","type":"number"},"out_of_domain_message":{"description":"Message used as a final answer when the input query is out of domain.","type":"string"}},"type":"object"},"v1ExchangeAudioInput":{"description":"Optional.","properties":{"audio_encoding":{"$ref":"#/components/schemas/v1ExchangeAudioInputAudioEncoding"},"sample_rate_hertz":{"description":"Sample rate in hertz of the audio data; valid value must be explicitly stated as 16000.","format":"int32","type":"integer"},"content":{"description":"The bytes of audio data encoded as specified in audio_encoding.","format":"byte","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$","type":"string"}},"type":"object"},"v1ExchangeAudioInputAudioEncoding":{"description":"- UNSPECIFIED_AUDIO_ENCODING: Encoding not specified; this is the default value and if received triggers an ERROR response message.\n - LINEAR16: Uncompressed 16-bit signed little-endian samples.","title":"Audio encoding of the content in the message\nAudio must be one-channel (mono)","type":"string"},"v1ExchangeAudioOutput":{"properties":{"audio_output_id":{"description":"Unique identifier generated by the entity creating the audio output resource.","type":"string"},"audio_encoding":{"$ref":"#/components/schemas/v1ExchangeAudioOutputAudioEncoding"},"sample_rate_hertz":{"description":"Sample rate in hertz of the audio data returned.","format":"int32","type":"integer"},"content":{"description":"The bytes of audio data encoded as specified in audio_encoding.","format":"byte","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$","type":"string"}},"type":"object"},"v1ExchangeAudioOutputAudioEncoding":{"description":"- UNSPECIFIED_AUDIO_ENCODING: Not specified; this is the default value.\n - LINEAR16: Uncompressed 16-bit signed little-endian samples.\n - MP3: Audio encoding; sample rate is encoded in the payload.","title":"Audio encoding of the content in the message","type":"string"},"v1ExchangeEventSSEData":{"description":"Important note: For forward compatibility, the client implementation should ignore states that are not relevant to them.","properties":{"metadata":{"$ref":"#/components/schemas/v1ResourceMetadata"},"state":{"$ref":"#/components/schemas/v1ExchangeEventSSEDataState"},"exchange_input_text":{"description":"The user input processed and interpreted by the LLM; returned with GENERATIVE_EXCHANGE_INPUT_DELTA and GENERATIVE_EXCHANGE_INPUT_COMPLETE states.","type":"string"},"exchange_response_data":{"$ref":"#/components/schemas/v1ExchangeResponseData"},"generative_exchange_conversation_data":{"$ref":"#/components/schemas/v1GenerativeExchangeConversationData"},"error":{"$ref":"#/components/schemas/rpcStatus"}},"title":"ExchangeEventSSEData represents the data associated with an exchange event using server-sent events (SSE).\nThe events encompass the following:\n- The outcome of LLM's interpretation of a question query\n- The response from LLM to a chit-chat question query\n- The determination of the best answers by domain-specific models\n- The answer provided by LLM based on the given context","type":"object"},"v1ExchangeEventSSEDataState":{"description":" - UNSPECIFIED: Default response.\n - GENERATIVE_EXCHANGE_INPUT_DELTA: Partial response to how the LLM interpreted the exchange input query.\n - GENERATIVE_EXCHANGE_INPUT_COMPLETE: Indicates that the API has finished sending the full response of how the LLM interpreted the input query.\n - EXCHANGE_RESPONSE_COMPLETE: Best answers as determined by domain-specific models.\n - GENERATIVE_EXCHANGE_RESPONSE_DELTA: Partial response to how the LLM interpreted the exchange response.\n - GENERATIVE_EXCHANGE_RESPONSE_COMPLETE: Indicates a full response to how the LLM interpreted the exchange response.\n - ERROR: Indicates an unsupported request or the API server problems; closes the connection.","type":"string"},"v1ExchangeInput":{"description":"Type of input, for example, text or audio.","properties":{"option":{"$ref":"#/components/schemas/v1ExchangeInputOption"},"language_id":{"description":"Language; default is en-US (US English)","type":"string"},"raw_text":{"description":"Input query to be used for retrieval.","type":"string"},"raw_audio":{"description":"Audio file that retains the original audio signal.","$ref":"#/components/schemas/v1ExchangeAudioInput"},"recommended_questions":{"$ref":"#/components/schemas/ExchangeInputAdditionalQuestionRequest"}},"type":"object"},"v1ExchangeInputFilter":{"properties":{"condition":{"description":"Filter conditions are written as strings.\n\nA single comparable condition is written as <type> <comparison operator> <value>\n- <type> is the subject category display name you want to filter on.\n  If the type string contains non-alphanumeric characters, it must be surrounded by backquotes.\n- <comparison operator> is the comparison operator. Only the “=” operator is supported.\n- <value> is the subject term for the filter\n\nYou can combine conditions with AND, OR operators.\n\nFor example,\n(Star = 'Harrison Ford' AND (Creator = 'George Lucas' OR Director = 'Steven Spielberg'))","type":"string"}},"type":"object"},"v1ExchangeInputOption":{"properties":{"audio_output_enabled":{"description":"If set to true, the system will respond with audio output when available. When audio output cannot be generated, successful exchange responses will include only text output. Default is false.","type":"boolean"},"knowledge_domain_id":{"description":"Version of a collection. If not defined, the active version of the collection is automatically used.\nLocation: The collection overview tab in the Advanced details listed as the Active Domain ID.\nIf both knowledge_domain_id and collection_id are set, the exchange operation will use knowledge_domain_id as the more specific of the two.","type":"string"},"max_outputs":{"description":"Specifies the number of outputs to be returned (min 3, max 10). Default is 3.","format":"int32","type":"integer"},"collection_id":{"description":"The knowledge collection, or index, that the exchange is performed against.\nLocation: The collection overview tab in the Advanced details.\nThe exchange operation will automatically determine and use the active version of this collection.","type":"string"},"max_sentence_outputs":{"description":"Specifies the number of answer snippets returned per chunk. The default is 1 and the max is 10.","format":"int32","type":"integer"},"max_concise_outputs":{"description":"If set, specifies the number of concise spans to be returned per top-level output (min 1, max 10). Default is 1.","format":"int32","type":"integer"},"content_group_ids":{"description":"Specifies the content groups used to return data.\nContent_group_ids can be retrieved via the contents API.","items":{"type":"string"},"type":"array"},"subject_ids":{"description":"Optional. Specifies the subjects used to return data.","items":{"type":"string"},"type":"array"},"filter":{"$ref":"#/components/schemas/v1ExchangeInputFilter"},"context":{"description":"Additional context for this exchange input.\nThe system will use the context to improve response ranking quality perceived by the user who is making the request.","properties":{},"type":"object"}},"type":"object"},"v1ExchangeOutput":{"properties":{"output_id":{"description":"Unique identifier generated by the entity creating the output resource.","type":"string"},"text":{"description":"Answer snippet or reply displayed to the user.","type":"string"},"summary_text":{"description":"Reply intended for translation to speech to be played as audio for the end-user; shorter form equivalent to text that works better as a spoken reply.","type":"string"},"audio":{"$ref":"#/components/schemas/v1ExchangeAudioOutput"},"attachments":{"additionalProperties":{"$ref":"#/components/schemas/v1Attachment"},"description":"Additional information containing the conversation response to the request query.","type":"object"},"subject_ids":{"description":"Subjects associated with the output.","items":{"type":"string"},"type":"array"},"context":{"$ref":"#/components/schemas/v1Context"}},"type":"object"},"v1ExchangeResponseData":{"properties":{"exchange_id":{"description":"Unique ID of the exchange item.","type":"string"},"conversation_id":{"description":"For subsequent calls; saved in the client and returned on the next request.","type":"string"},"normalized_input":{"$ref":"#/components/schemas/v1NormalizedExchangeInput"},"output":{"description":"The exchange result.","items":{"$ref":"#/components/schemas/v1ExchangeOutput"},"type":"array"}},"type":"object"},"v1GenerativeExchangeConversationData":{"properties":{"data":{"$ref":"#/components/schemas/v1GenerativeExchangeResponseData"},"conversation_context":{"description":"String representing the conversation context; passed back to the server in the next request and not intended for direct use by a client.","type":"string"}},"type":"object"},"v1GenerativeExchangeResponseData":{"properties":{"text":{"description":"String containing the text output of the generative exchange.","type":"string"},"reference":{"description":"Information about a specific reference made in the text output of the generative exchange, including the start and end indices of the reference, and the index of the corresponding exchange output.","items":{"$ref":"#/components/schemas/v1Reference"},"type":"array"},"generative_exchange_id":{"description":"Unique ID of the generative exchange associated with the response.","type":"string"},"knowledge_domain_id":{"description":"Unique identifier of the knowledge domain associated with the generative exchange being created.","type":"string"},"exchange_id":{"description":"Unique ID of the exchange item.","type":"string"},"collection_id":{"description":"Unique ID of the collection associated with the generative exchange being created.","type":"string"}},"type":"object"},"v1NormalizedExchangeInput":{"properties":{"normalized_input_id":{"description":"Unique identifier generated by the entity creating the normalized input resource.","type":"string"},"raw_text":{"description":"Original input query.","type":"string"},"understood_text":{"description":"The normalized input query, that is, raw text, which creates the output.","type":"string"},"understood_subject_ids":{"description":"IDs of subjects found in the input that filter the outputs.","items":{"type":"string"},"type":"array"},"suggested_raw_texts":{"description":"Spelling corrections, if any, or other suggestions found for the input query (raw_text).","items":{"type":"string"},"type":"array"}},"type":"object"},"v1Reference":{"properties":{"text_index_start":{"description":"Integer representing the start index of the reference in the text output of the generative exchange; indexing starts at 1 and 0 is inconsequential.","format":"int32","type":"integer"},"text_index_end":{"description":"Integer representing the end index of the reference in the text output of the generative exchange; indexing starts at 1 and 0 is inconsequential.","format":"int32","type":"integer"},"exchange_output_index":{"description":"Integer representing the index of the exchange output that the reference corresponds to; indexing starts at 1 and 0 is inconsequential.","format":"int32","type":"integer"}},"type":"object"},"v1ResourceMetadata":{"properties":{"uuid":{"description":"Unique identifier for the interaction returned in the resource response; the response ID.","type":"string"},"create_time":{"description":"Time of the initial request.","format":"date-time","type":"string"},"update_time":{"description":"Time of the last update; 0 indicates updates have never been made.","format":"date-time","type":"string"},"response_time_millis":{"description":"Response time (in milliseconds).","format":"int64","title":"Time difference in milliseconds between the request being received and the response being generated","type":"integer"}},"type":"object"}}},"x-original-swagger-version":"2.0"}