Pryon Exchange Event API
The ExchangeEvent API from Pryon — 1 operation(s) for exchangeevent.
OpenAPI Specification
openapi: 3.2.0
info:
title: Pryon Exchange Event API
version: '1.0'
description: 'Operations tagged ExchangeEvent across 2 of this provider''s published API definitions: pryon-admin-openapi.json, pryon-exchange-event-may2025-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.pryon.net
description: Pryon Cloud
- url: /
tags:
- name: ExchangeEvent
paths:
/api/conversation/v1/exchange-events/sse:
servers:
- url: https://api.pryon.net
description: Pryon Cloud
post:
description: 'CreateExchangeEventSSE Service:
This service sends ExchangeEventSSEData messages as "Data-Only" Server-Sent Events (SSE). The stream terminates with a ExchangeEventSSEData message containing the GENERATIVE_EXCHANGE_RESPONSE_COMPLETE state.
Each message is sent approximately within a second or less of each other. If clients do not receive a message within their specified timeout, they should assume the connection is lost and attempt to reconnect.
Reference:
https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events
https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format
The following sequence of messages is sent for a single exchange request:
- Clients establish a connection to the service by issuing a POST request to the /api/conversation/v1/exchange-events/sse endpoint.
- The server processes the request and sends a response with a 200 OK status code, Content-Type header set to text/event-stream.
Usecase 1: Casual conversation from a input query of "Hello."
- The first "Data-Only" message with a state of "GENERATIVE_EXCHANGE_RESPONSE_DELTA". Note that there is no Metadata or Reference in "DELTA" messages.
- The final message is sent when the service has completely processed the generative exchange request of casual query, and the server terminates the stream.
Example Messages:
Message 1: data: {"state": 40,"data": {"text": "How"}}
Message 2: data: {"state": 40,"data": {"text": " "}}
Message 3: data: {"state": 40,"data": {"text": "can"}}
Message 4: data: {"state": 40,"data": {"text": " "}}
Message 5: data: {"state": 40,"data": {"text": "I"}}
Message 6: data: {"state": 40,"data": {"text": " "}}
Message 7: data: {"state": 40,"data": {"text": "help"}}
Message 8: data: {"state": 40,"data": {"text": " "}}
Message 9: data: {"state": 2,"data": {"text": "you"}}
Message 10: data: {"state": 2,"data": {"text": "?"}}
Usecase 2: Question/Answering from a input query of "How old is Yoda?"
Messages are sent in the following sequences:
- N numbers of GENERATIVE_EXCHANGE_INPUT_DELTA messages
- GENERATIVE_EXCHANGE_INPUT_COMPLETE
- EXCHANGE_RESPONSE_COMPLETE
- M numbers of GENERATIVE_EXCHANGE_RESPONSE_DELTA messages
- GENERATIVE_EXCHANGE_RESPONSE_COMPLETE'
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: CreateExchangeEventSSE
tags:
- ExchangeEvent
x-codegen-request-body-name: body
parameters:
- name: Authentication
in: header
required: true
schema:
type: string
example: 'Authorization: Bearer {base64-encoded-token}'
components:
schemas:
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
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
v1NormalizedExchangeInput:
properties:
normalized_input_id:
description: UUID 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 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
v1GenerativeExchangeResponseData:
properties:
text:
description: Required. A string containing the text output of the generative exchange.
type: string
reference:
description: Optional. A Reference message containing information about a specific reference made in the text output of the generative exchange, including the start and end indices of the reference in the text, and the index of the exchange output that the reference corresponds to.
items:
$ref: '#/components/schemas/v1Reference'
type: array
generative_exchange_id:
description: Required. An ID representing the generative_exchange_id associated with this response object generated by the LLM.
type: string
knowledge_domain_id:
description: Required. A string representing the ID of the knowledge domain associated with the generative exchange being created.
type: string
exchange_id:
description: Optional. An ID representing an extractive exchange_id associated with this response object from sources.
type: string
collection_id:
description: Optional. An ID representing the ID of the collection associated with the generative exchange being created.
type: string
type: object
rpcStatus:
properties:
code:
format: int32
type: integer
message:
type: string
details:
items:
$ref: '#/components/schemas/protobufAny'
type: array
type: object
v1ResourceMetadata:
properties:
uuid:
description: UUID returned in the resource response, which represents the unique interaction with the API, that is, 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.
A value of 0 indicates it has never been updated.'
format: date-time
type: string
response_time_millis:
format: int64
title: Time difference in milliseconds between when the request was received and when the response was generated
type: integer
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: 'Optional. Version of a collection. If not defined, the active version of the collection is automatically used.
Location: The collection overview tab in the Advanced details listed as the Active Domain ID.
If 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: Optional. Specifies the number of outputs to be returned (min 3, max 10). Default is 3.
format: int32
type: integer
collection_id:
description: 'Required. The knowledge collection, or index, that the exchange is performed against.
Location: The collection overview tab in the Advanced details.
The exchange operation will automatically determine and use the active version of this collection.'
type: string
max_sentence_outputs:
description: Optional. 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: 'Optional. Specifies the content groups used to return data.
Content_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.
The system will use the context to improve response ranking quality perceived by the user who is making the request.'
properties: {}
type: object
type: object
protobufAny:
properties:
type_url:
type: string
value:
format: byte
pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
type: string
type: object
v1ExchangeEventSSEDataState:
default: UNSPECIFIED
description: " - UNSPECIFIED: Not specified.\n - GENERATIVE_EXCHANGE_INPUT_DELTA: Required. This is partial data indicating how the large language model interpreted the exchange input query.\n - GENERATIVE_EXCHANGE_INPUT_COMPLETE: Required. The \"GENERATIVE_EXCHANGE_INPUT_COMPLETE\" state indicates that the API has finished sending the full response of how the large language model interpreted the input query.\n - EXCHANGE_RESPONSE_COMPLETE: This is the determination of the best answers by domain-specific models\n - GENERATIVE_EXCHANGE_RESPONSE_DELTA: Required. This is partial data indicating how the large language model interpreted the exchange response.\n - GENERATIVE_EXCHANGE_RESPONSE_COMPLETE: Required. The \"GENERATIVE_EXCHANGE_RESPONSE_COMPLETE\" state indicates that the API has finished sending the full response of how the large language model interpreted the exchange response.\n - ERROR: The \"ERROR\" state 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."
enum:
- UNSPECIFIED
- GENERATIVE_EXCHANGE_INPUT_DELTA
- GENERATIVE_EXCHANGE_INPUT_COMPLETE
- EXCHANGE_RESPONSE_COMPLETE
- GENERATIVE_EXCHANGE_RESPONSE_DELTA
- GENERATIVE_EXCHANGE_RESPONSE_COMPLETE
- ERROR
type: string
v1ExchangeResponseData:
properties:
exchange_id:
description: 'UUID generated by the entity creating the exchange response data resource.
The exchange_id can be used in the "feedback" API.'
type: string
conversation_id:
description: Conversation ID for subsequent calls, which is 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
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
v1ExchangeAudioInput:
description: Optional.
properties:
audio_encoding:
$ref: '#/components/schemas/v1ExchangeAudioInputAudioEncoding'
sample_rate_hertz:
description: 'Sample rate in Hertz of the audio data.
The 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".
Note: 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
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
v1ExchangeAudioOutput:
properties:
audio_output_id:
description: Random UUID 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".
Note: 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
v1CreateExchangeEventRequest:
description: CreateExchangeEventRequest represents a request to create a new exchange event.
properties:
input:
$ref: '#/components/schemas/v1ExchangeInput'
conversation_context:
description: 'Conversation context: Obtained from the previous response''s ExchangeEventSSEData generative_exchange_conversation_data.conversation_context. This is used to enhance the generative response. This context is utilized to improve the generative response. Modifying a conversation context string from previous responses will lead to errors.'
type: string
randomness:
description: Controls the randomness of the generated text, ranging from 0 to 1. Higher values result in more random text, while lower values produce more focused and deterministic text. The default value is 0, promoting deterministic and repetitive generative text.
format: float
type: number
max_answer_in_contexts_num:
description: Determines the maximum number of ExchangeOutput's answer_in_contexts to be considered when generating a response. The value must be greater than 0. The default value is 3.
format: int32
type: integer
min_answer_in_contexts_score:
description: Sets the minimum score of ExchangeOutput's answer_in_contexts to be considered when generating a response. The value must be between 0 and 1. The default value is 0.55.
format: float
type: number
answer_in_contexts_beam_delta_cutoff:
description: A maximum allowable answer_in_context's score delta from the highest score to be considered when generating a response. The value must be between 0 and 1. The default value is set to 0.1.
format: float
type: number
verified_answer_score_threshold:
description: Threshold of verified answer to be considered as a final answer. The value must be between 0 and 1. The default value is 0.55.
format: float
type: number
out_of_domain_score_threshold:
description: Threshold of best answer score which out of domain message should be returned as a final answer. The value must be between 0 and 1. The default value is 0.55.
format: float
type: number
out_of_domain_message:
description: The message to be used as a final answer when the input query is out of domain.
type: string
type: object
v1Reference:
properties:
text_index_start:
description: 'Required. An integer representing the start index of the reference in the text output of the generative exchange.
Indexing starts at 1. Value of 0 is inconsequential.'
format: int32
type: integer
text_index_end:
description: 'Required. An integer representing the end index of the reference in the text output of the generative exchange.
Indexing starts at 1. Value of 0 is inconsequential.'
format: int32
type: integer
exchange_output_index:
description: 'Required. An integer representing the index of the exchange output that the reference corresponds to.
Indexing starts at 1. Value of 0 is inconsequential.'
format: int32
type: integer
type: object
v1GenerativeExchangeConversationData:
properties:
data:
$ref: '#/components/schemas/v1GenerativeExchangeResponseData'
conversation_context:
description: A string representing the conversation context. This string should be passed back to the server in the next request and is not intended for direct use by a client.
type: string
type: object
v1ExchangeInput:
description: 'The "input" message provides input information to the Conversation system
specifies the type of input, text or audio.'
properties:
option:
$ref: '#/components/schemas/v1ExchangeInputOption'
language_id:
title: 'W3C Language Tags (https://www.w3.org/International/articles/language-tags/)
Defaults 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
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
Audio must be one-channel (mono)'
type: string
ExchangeInputAdditionalQuestionRequest:
default: UNSPECIFIED
description: "Optional. Specifies whether to include related questions in the response.\n\n - UNSPECIFIED: UNSPECIFIED: Default option, none requested\n - RELATED: RELATED: Request only related questions\n - FOLLOWUP: 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
v1ExchangeOutput:
properties:
output_id:
description: UUID 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 exchange reply that is intended to be translated to speech and played as audio for the end-user. This is generally a shorter form equivalent to "text" that works better as a spoken reply. If there is no shorter form summarization available, this will be empty, and "text" will be 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
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''s input text that was processed/interpreted by the large language model. It may or may not equal to the user''s input text.
This is 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).
The events encompass the following:
- The outcome of LLM''s interpretation of a question query
- The response from LLM to a chit-chat question query
- The determination of the best answers by domain-specific models
- The answer provided by LLM based on the given context'
type: object
x-refined-from:
- pryon-admin-openapi.json
- pryon-exchange-event-may2025-openapi.json
x-original-swagger-version: '2.0'
x-tagGroups:
- name: Retrieval
tags:
- Exchange
- ExchangeEvent
- Feedback
- GenerativeExchange
- GenerativeFeedback
- TextToSpeech
- name: Reporting
tags:
- Analytics
- Reports
- Usage
- name: Collection Management
tags:
- KnowledgeCollectionService
- KnowledgeDomain
- ContentService
- RegressionTest
- Subjects
- name: Organization Management
tags:
- ConnectorServiceExternal
- OrganizationService
- Messages
- name: Ops Console
tags:
- Operations