Pryon Exchange API

openapi: 3.2.0
info:
  title: Pryon Exchange API
  version: '1.0'
  description: 'Operations tagged Exchange across 2 of this provider''s published API definitions: pryon-admin-openapi.json, pryon-exchange-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: Exchange
paths:
  /api/conversation/v1/exchange:
    servers:
    - url: https://api.pryon.net
      description: Pryon Cloud
    post:
      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: CreateExchange
      tags:
      - Exchange
      x-codegen-request-body-name: body
      description: 'Initiates or continues a conversation with the conversation exchange service.

        Each call performs one synchronous round-trip by sending a text or audio request to the service and receiving the text and optional audio response.'
      parameters:
      - name: Authentication
        in: header
        required: true
        schema:
          type: string
        example: 'Authorization: Bearer {base64-encoded-token}'
  /api/conversation/v1/exchange/wss:
    servers:
    - url: https://api.pryon.net
      description: Pryon Cloud
    post:
      description: "Initiates or continues a conversation with the conversation exchange service.\nThe conversation exchange request and response cycle has the following steps.\n\n1. Open a connection.\n\nThe conversation exchange service uses the secure WebSocket protocol (wss) at the following endpoint:\nwss://{hostname}/api/conversation/v1/exchange/wss\n\nAfter the connection is established, the client defines the event listeners (onOpen, onMessage, onClose, etc) to respond to events from the server.\n\n2. Initiate an exchange request.\n\nTo initiate an exchange request, the client sends a JSON text message to the service over the established connection.\nThe client must send this message before it sends any audio.\nThe JSON text message must include an \"action\" parameter.\n\nFor example,\n{\n  \"action\": \"START\",\n  \"exchange_request\": {\n    \"conversation_id\": \"conversation-59410397-aaa9-42f0-91ef-1e39f710edec\",\n    \"input\": {\n      \"option\": {\n        \"audio_output_disabled\": true,\n      },\n      \"raw_audio\": {\n        \"audio_encoding\": \"LINEAR16\",\n        \"sample_rate_hertz\": 16000,\n      }\n    }\n  }\n}\n\nIf the service receives the request successfully, the service returns the following JSON text message to indicate that it is \"PROCESSING\".\n\n{\n \"data\": {\n   \"state\": \"PROCESSING\"\n }\n}\n\n3. Send audio.\n\nAfter the client sends the initial \"START\" message, it can start sending audio data to the service.\nThe client does not need to wait for the service to respond to the \"START\" message with the \"PROCESSING\" message.\n\n4. End a request.\n\nWhen the client is done sending the audio data, it must signal the service by sending a JSON text message with the action parameter set to the value of \"STOP\".\n\n{\n  \"action\": \"STOP\"\n}\n\n5. Receive exchange result\n\nOnce the service receives the \"STOP\" action from the client and finishes processing the request,\nit will send a response JSON text message (CreateWsExchangeResponse message type) asynchronously,\nfollowed by { \"data\": { \"state\" : \"PROCESSING_COMPLETED\" } } indicating that it's done sending the response."
      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: CreateWsExchange
      tags:
      - Exchange
      x-codegen-request-body-name: body
      parameters:
      - name: Authentication
        in: header
        required: true
        schema:
          type: string
        example: 'Authorization: Bearer {base64-encoded-token}'
  /api/conversation/v1/exchanges/{exchange_id}:
    servers:
    - url: https://api.pryon.net
      description: Pryon Cloud
    get:
      operationId: Exchange_GetExchange
      parameters:
      - description: Required. Valid Unique ID of the exchange item from /api/knowledge/v1/exchanges
        in: path
        name: exchange_id
        required: true
        schema:
          type: string
      - description: Optional. The ranking of the answer and answer_in_context chunk, represented as best_1, best_2, etc.
        in: query
        name: output_id
        schema:
          type: string
      - name: Authentication
        in: header
        required: true
        schema:
          type: string
        example: 'Authorization: Bearer {base64-encoded-token}'
      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: GetExchange
      tags:
      - Exchange
      description: Retrieves the query and output data for an existing exchange data when supplied with an exchange_id and optional output_id.
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
    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: UUID of the knowledge domain that supplied this exchange response
          type: string
        collection_id:
          title: UUID of the knowledge collection that supplied this exchange response
          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
    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: UUID of the knowledge domain that supplied this exchange response
          type: string
        collection_id:
          title: UUID of the knowledge collection that supplied this exchange response
          type: string
      type: object
    CreateWsExchangeRequestAction:
      default: UNSPECIFIED_ACTION
      description: " - UNSPECIFIED_ACTION: UNSPECIFIED_ACTION: This indicates that an action 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, and the connection will be closed by the server.\n - START: START: signals the intent to begin an exchange. If an existing conversation is being continued, then conversation_id should be set to the value used in previous exchanges.\nIf text input mode is being used, this text-based message must also include the complete input.raw_text.\nIf audio input mode is being used, this text-based message must include valid input.raw_audio.audio_encoding and input.raw_audio.sample_rate_hertz fields. It cannot include input.raw_audio.content, as input audio should be sent in binary messages that follow. If invalid values are requested for audio_encoding and/or sample_rate_hertz, then an ERROR response message will be sent, and the connection will be closed by the server.\nIn both text and audio input modes, a successful start request will be acknowledged by the server with a PROCESSING text message. Frames of audio should be sent by the client as binary messages following receipt of this PROCESSING text message.  After all frames of audio have been sent, a STOP message should be sent by the client.\n - STOP: STOP: This message should be sent following the START message. When audio input mode is being used, STOP should be sent by the client after all audio frames have been sent to the server."
      enum:
      - UNSPECIFIED_ACTION
      - START
      - STOP
      type: string
    v1WsExchangeResponseData:
      properties:
        state:
          $ref: '#/components/schemas/WsExchangeResponseDataState'
        exchange:
          $ref: '#/components/schemas/v1ExchangeResponseData'
        error:
          $ref: '#/components/schemas/rpcStatus'
      type: object
    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
    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:
          description: UUID of the knowledge domain that supplied the exchange response.
          type: string
        collection_id:
          description: UUID of the knowledge collection that supplied the exchange response.
          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
    WsExchangeResponseDataState:
      default: UNSPECIFIED_STATE
      description: " - UNSPECIFIED_STATE: UNSPECIFIED_STATE: Not specified.\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.\n - PROCESSING: The \"PROCESSING\" state 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: The \"QUERY_RESULT\" state 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: The \"PROCESSING_COMPLETED\" state indicates that the API has completed sending the full response for an exchange request."
      enum:
      - UNSPECIFIED_STATE
      - ERROR
      - PROCESSING
      - QUERY_RESULT
      - PROCESSING_COMPLETED
      type: string
    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
    v1CreateExchangeRequest:
      description: The top-level message sent by the client for the CreateExchange method.
      properties:
        conversation_id:
          title: 'Optional. The conversation_id value returned in the prior CreateExchangeResponse.

            Omitting conversation_id will start a new conversation on the request'
          type: string
        input:
          $ref: '#/components/schemas/v1ExchangeInput'
      type: object
    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
x-refined-from:
- pryon-admin-openapi.json
- pryon-exchange-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