{"openapi":"3.0.1","info":{"title":"Exchange","version":"1.0"},"servers":[{"url":"/"}],"paths":{"/api/conversation/v1/exchange":{"post":{"description":"Reviews the conversation exchange request and response cycle.","operationId":"Exchange_CreateExchange","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CreateExchangeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CreateExchangeResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}},"description":"An unexpected error response."}},"summary":"Review Conversation Response","tags":["Exchange"],"x-codegen-request-body-name":"body"}},"/api/conversation/v1/exchange/wss":{"post":{"description":"Start or continue an existing conversation.","operationId":"Exchange_CreateWsExchange","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CreateWsExchangeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CreateWsExchangeResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}},"description":"An unexpected error response."}},"summary":"Initiate or Continue Exchange","tags":["Exchange"],"x-codegen-request-body-name":"body"}},"/api/conversation/v1/exchanges/{exchange_id}":{"get":{"description":"Retrieve collection information on questions asked and responses returned during the course of an exchange.","operationId":"Exchange_GetExchange","parameters":[{"description":"Unique ID of the exchange item.","in":"path","name":"exchange_id","required":true,"schema":{"type":"string"}},{"description":"Ranking of answers and answer_in_context chunks, in rank order, for example, best_1, best_2.","in":"query","name":"output_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetExchangeResponse"}}},"description":"A successful response."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}},"description":"An unexpected error response."}},"summary":"Retrieve Exchange Query and Response","tags":["Exchange"]}}},"components":{"schemas":{"CreateWsExchangeRequestAction":{"description":" - UNSPECIFIED_ACTION: Not specified; this is the default value and if received triggers an ERROR response message.\n - START: Signals the intent to begin an exchange.\nExisting conversations: set the conversation_id to the value used in previous exchanges.\nText input: include the complete input.raw_text.\nAudio input: include valid input.raw_audio.audio_encoding and input.raw_audio.sample_rate_hertz fields sent in binary messages; invalid values result in an ERROR response and close the connection.\nSuccessful start requests return a PROCESSING message, allowing you to send frames of audio as binary messages.\n - STOP: Sent following the START message. For audio input mode, sent by the client after all audio frames have been sent to the server.","enum":["UNSPECIFIED_ACTION","START","STOP"],"type":"string"},"ExchangeInputAdditionalQuestionRequest":{"default":"UNSPECIFIED","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: RELATED_AND_FOLLOWUP: Request both related and follow-up questions.","enum":["UNSPECIFIED","RELATED","FOLLOWUP","RELATED_AND_FOLLOWUP"],"type":"string"},"WsExchangeResponseDataState":{"default":"UNSPECIFIED_STATE","description":" - UNSPECIFIED_STATE: Not specified.\n - ERROR: Indicates that an unsupported request has been received or the API server is having problems. The server will always follow an ERROR response by closing the connection.\n - PROCESSING: Indicates that the API has successfully received a START request for audio input and is ready to receive binary messages with audio frames followed by a STOP text message from the client. This message will include the conversation_id and exchange_id values that will be preserved all the way through to the end of the exchange.\n - QUERY_RESULT: Indicates that the API has returned the exchange response to the client. The result will include the complete text response. If audio output is enabled, it will be sent as binary messages that precede PROCESSING_COMPLETED.\n - PROCESSING_COMPLETED: Indicates that the API has completed sending the full response for an exchange request.","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":"A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n  value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n  URL, or have them precompiled into a binary to avoid any\n  lookup. Therefore, binary compatibility needs to be preserved\n  on changes to types. (Use versioned type names to manage\n  breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics.","type":"string"},"value":{"description":"Must be a valid serialized protocol buffer of the above specified type.","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":"The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].","format":"int32","type":"integer"},"message":{"description":"A developer-facing error message, which should be in English. Any\nuser-facing error message should be localized and sent in the\n[google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.","type":"string"},"details":{"description":"A list of messages that carry the error details.  There is a common set of\nmessage types for APIs to use.","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. See \"documentation about augmenting\" link.","properties":{},"type":"object"}},"type":"object"},"v1CreateExchangeRequest":{"description":"The top-level message sent by the client for CreateExchange.","properties":{"conversation_id":{"title":"Optional. The conversation_id value returned in the prior CreateExchangeResponse.\nOmitting conversation_id will start a new conversation on the request","type":"string"},"input":{"$ref":"#/components/schemas/v1ExchangeInput"}},"type":"object"},"v1CreateExchangeResponse":{"description":"The only top-level message returned to the client by the \"CreateExchange\" method.","properties":{"metadata":{"$ref":"#/components/schemas/v1ResourceMetadata"},"data":{"$ref":"#/components/schemas/v1ExchangeResponseData"},"user_id":{"title":"The identifier of the user that originally made the exchange","type":"string"},"knowledge_domain_id":{"title":"Unique identifier of the knowledge domain that supplied the exchange response.","description":"Unique identifier of the knowledge domain that supplied the exchange response.","type":"string"},"collection_id":{"title":"Unique identifier of the knowledge collection that supplied the exchange response","description":"Unique identifier of the knowledge collection that supplied the exchange response.","type":"string"}},"type":"object"},"v1CreateWsExchangeRequest":{"description":"The top-level message sent by the client for the CreateWsExchange (WebSocket) method.","properties":{"action":{"$ref":"#/components/schemas/CreateWsExchangeRequestAction"},"exchange_request":{"$ref":"#/components/schemas/v1CreateExchangeRequest"}},"type":"object"},"v1CreateWsExchangeResponse":{"description":"The only top-level message returned to the client by the \"CreateWsExchange\" (WebSocket) method.","properties":{"metadata":{"$ref":"#/components/schemas/v1ResourceMetadata"},"data":{"$ref":"#/components/schemas/v1WsExchangeResponseData"},"user_id":{"title":"The identifier of the user that originally made the exchange","type":"string"},"knowledge_domain_id":{"title":"Unique identifier of the knowledge domain that supplied the exchange response.","description":"Unique identifier of the knowledge domain that supplied the exchange response.","type":"string"},"collection_id":{"title":"Unique identifier of the knowledge collection that supplied this exchange response","description":"Unique identifier of the knowledge collection that supplied the exchange response.","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.\nThe only valid value currently supported is 16000, which must be explicitly stated by the client.","format":"int32","type":"integer"},"content":{"description":"The bytes of audio data encoded as specified in \"audio_encoding\".\nNote: as with all bytes fields, protobuffers use a pure binary representation, whereas JSON representations use base64.","format":"byte","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$","type":"string"}},"type":"object"},"v1ExchangeAudioInputAudioEncoding":{"default":"UNSPECIFIED_AUDIO_ENCODING","description":"- UNSPECIFIED_AUDIO_ENCODING: UNSPECIFIED_AUDIO_ENCODING: This indicates that an encoding was not specified, as it is the protobuf default.  This is never a valid value and if received then an ERROR response message will be returned.\n - LINEAR16: LINEAR16: Uncompressed 16-bit signed little-endian samples (Linear PCM).","enum":["UNSPECIFIED_AUDIO_ENCODING","LINEAR16"],"title":"Audio encoding of the content in the message\nAudio must be one-channel (mono)","type":"string"},"v1ExchangeAudioOutput":{"properties":{"audio_output_id":{"description":"Random Unique identifier generated by the entity creating the audio output resource.","type":"string"},"audio_encoding":{"$ref":"#/components/schemas/v1ExchangeAudioOutputAudioEncoding"},"sample_rate_hertz":{"description":"The sample rate in Hertz of the audio data returned in \"content\".","format":"int32","type":"integer"},"content":{"description":"The bytes of audio data encoded as specified in \"audio_encoding\".\nNote: as with all bytes fields, protobuffers use a pure binary representation, whereas JSON representations use base64.","format":"byte","pattern":"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$","type":"string"}},"type":"object"},"v1ExchangeAudioOutputAudioEncoding":{"default":"UNSPECIFIED_AUDIO_ENCODING","description":"- UNSPECIFIED_AUDIO_ENCODING: UNSPECIFIED: Not specified.\n - LINEAR16: LINEAR16: Uncompressed 16-bit signed little-endian samples (Linear PCM).\n - MP3: MP3: MP3 audio encoding. The sample rate is encoded in the payload.","enum":["UNSPECIFIED_AUDIO_ENCODING","LINEAR16","MP3"],"title":"Audio encoding of the content in the message","type":"string"},"v1ExchangeInput":{"description":"Type of input, for example, text or audio.","properties":{"option":{"$ref":"#/components/schemas/v1ExchangeInputOption"},"language_id":{"title":"W3C Language Tags (https://www.w3.org/International/articles/language-tags/)\nDefaults is en-US","type":"string"},"raw_text":{"description":"Required. Input query to be used for retrieval.","type":"string"},"raw_audio":{"$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":"The answer snippet or reply displayed to the end-user.","type":"string"},"summary_text":{"description":"The reply to be translated to speech and played as audio for the end-user; generally a shorter form equivalent to text that works better as a spoken reply; if no shorter form summarization is available, this is empty, and the text is synthesized into speech.","type":"string"},"audio":{"$ref":"#/components/schemas/v1ExchangeAudioOutput"},"attachments":{"additionalProperties":{"$ref":"#/components/schemas/v1Attachment"},"description":"The additional information containing the conversation response to the request query, keyed by a UUIDv4 string.","type":"object"},"subject_ids":{"description":"The subjects known to be associated with this 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":"Unique identifier 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"},"v1GetExchangeResponse":{"properties":{"metadata":{"$ref":"#/components/schemas/v1ResourceMetadata"},"data":{"$ref":"#/components/schemas/v1ExchangeResponseData"},"user_id":{"title":"The identifier of the user that originally made the exchange","type":"string"},"knowledge_domain_id":{"title":"Unique identifier of the knowledge domain that supplied the exchange response.","description":"Unique identifier of the knowledge domain that supplied the exchange response.","type":"string"},"collection_id":{"description":"Unique identifier of the knowledge collection that supplied the exchange response.","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":"The original input query (raw_text).","type":"string"},"understood_text":{"description":"The normalized raw text query that creates the output.","type":"string"},"understood_subject_ids":{"description":"IDs of subjects; found in the input and helps to filter the output.","items":{"type":"string"},"type":"array"},"suggested_raw_texts":{"description":"Spelling corrections, if any, or other suggestions found for the raw text query.","items":{"type":"string"},"type":"array"}},"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":{"format":"int64","description":"Response time (in milliseconds).","type":"integer"}},"type":"object"},"v1WsExchangeResponseData":{"properties":{"state":{"$ref":"#/components/schemas/WsExchangeResponseDataState"},"exchange":{"$ref":"#/components/schemas/v1ExchangeResponseData"},"error":{"$ref":"#/components/schemas/rpcStatus"}},"type":"object"}}},"x-original-swagger-version":"2.0"}