Pryon Generative Retrieval API

openapi: 3.2.0
info:
  title: Generative Retrieval API
  version: '1.0'
  contact:
    name: Pryon Product Support
    url: https://pryon.zendesk.com
    email: support@pryon.zendesk.com
  description: ''
  x-logo:
    altText: Pryon APIs
servers:
- url: https://api.pryon.net
  description: Pryon Cloud
tags:
- name: GenerativeRetrieval
paths:
  /api/conversation/v1alpha1/generative-retrievals:
    post:
      description: Create a new generative retrieval using server-sent events (SSE).
      operationId: GenerativeRetrieval_CreateGenerativeRetrievalSSE
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/filename_v1alpha1CreateGenerativeRetrievalRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/filename_v1alpha1GenerativeRetrievalSSEData'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/filename_googlerpcStatus'
          description: An unexpected error response.
      summary: Create Generative Retrieval SSE
      tags:
      - GenerativeRetrieval
      x-codegen-request-body-name: body
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        example: 'Authorization: Bearer {base64-encoded-token}'
  /api/conversation/v1alpha1/generative-retrievals/{generative_retrieval_id}:
    get:
      operationId: GenerativeRetrieval_GetGenerativeRetrieval
      parameters:
      - description: Unique identifier for the generative response object.
        in: path
        name: generative_retrieval_id
        required: true
        schema:
          type: string
      - description: Unique identifier of the knowledge domain that supplied the generative exchange response.
        in: query
        name: knowledge_domain_id
        schema:
          type: string
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        example: 'Authorization: Bearer {base64-encoded-token}'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/filename_v1alpha1GetGenerativeRetrievalResponse'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/filename_googlerpcStatus'
          description: An unexpected error response.
      tags:
      - GenerativeRetrieval
      summary: Get Generative Retrieval
      description: Return a generative retrieval answer.
components:
  schemas:
    filename_v1alpha1RetrievalReference:
      properties:
        text_index_start:
          description: Start index of the reference in the text output of the generative retrieval; indexing starts at 1; value of 0 is inconsequential.
          format: int32
          type: integer
        text_index_end:
          description: End index of the reference in the text output of the generative retrieval; indexing starts at 1; value of 0 is inconsequential.
          format: int32
          type: integer
        retrieval_output_index:
          description: Index of the retrieval output that the reference corresponds to; indexing starts at 1; value of 0 is inconsequential.
          format: int32
          type: integer
      type: object
    filename_v1alpha1ContentGroupSparse:
      properties:
        content_group_id:
          title: Unique identifier for the content group.
          type: string
        display_name:
          title: Name of the collection.
          type: string
      title: Abbreviated form of ContentGroup for returning only the essential information.
      type: object
    filename_googlerpcStatus:
      properties:
        code:
          format: int32
          type: integer
        message:
          type: string
        details:
          items:
            $ref: '#/components/schemas/filename_protobufAny'
          type: array
      type: object
    filename_v1alpha1RetrievalAudioOutputAudioEncoding:
      default: UNSPECIFIED
      description: "- 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."
      title: Audio encoding of the content in the message
      type: string
    filename_v1alpha1TagSourceType:
      default: TAG_SOURCE_TYPE_UNSPECIFIED
      description: " - TAG_SOURCE_TYPE_UNSPECIFIED: Default. No tags can be created with this source.\n - SYSTEM_DEFINED: Tags created by the Pryon Cloud Services system.\n - USER_DEFINED: Tags defined by users if the system and created via user input.\n - QUERY_ATTRIBUTE: Tags associated to a content which can be used to improve Exchange response ranking quality based on the context specified in ExchangeInputOption."
      type: string
    filename_v1alpha1BoundingBox:
      properties:
        x1:
          format: float
          title: Required. top-left corner X-axis
          type: number
        y1:
          format: float
          title: Required. top-left corner Y-axis
          type: number
        x2:
          format: float
          title: Bottom-right corner X-axis.
          type: number
        y2:
          format: float
          title: Bottom-right corner Y-axis.
          type: number
        page_number:
          format: int32
          title: Page number where the bounding box was found.
          type: integer
        page_width:
          format: float
          title: The width of the page the bounding box was found on
          type: number
        page_height:
          format: float
          title: The height of the page the bounding box was found on
          type: number
      title: A rectangle bounding box typically for indicating where text matched on a page
      type: object
    filename_v1alpha1RetrievalFilter:
      properties:
        collection_id:
          description: Parent collection for the knowledge domain; autogenerated and not editable.
          type: string
        knowledge_domain_id:
          description: Unique identifier of the knowledge domain that supplied the exchange response.
          type: string
        content_group_ids:
          description: Unique identifier for the content group.
          items:
            type: string
          type: array
        tags:
          description: Tags used to return data.
          items:
            $ref: '#/components/schemas/filename_v1alpha1TagData'
          type: array
      title: Filters for limiting what content is searched
      type: object
    filename_v1alpha1GenerativeRetrievalSSEDataState:
      default: UNSPECIFIED
      description: " - UNSPECIFIED: Not specified.\n - GENERATIVE_RETRIEVAL_INPUT_COMPLETE: Required. The GENERATIVE_RETRIEVAL_INPUT_COMPLETE state indicates that the API has finished sending the full response of how the large language model interpreted the input query.\n - RETRIEVAL_RESPONSE_COMPLETE: This is the determination of the best answers by domain-specific models\n - GENERATIVE_RETRIEVAL_RESPONSE_DELTA: Required. This is partial data indicating how the large language model interpreted the response.\n - GENERATIVE_RETRIEVAL_RESPONSE_COMPLETE: Required. The GENERATIVE_RETRIEVAL_RESPONSE_COMPLETE state indicates that the API has finished sending\nthe full response of how the large language model interpreted the response.\n - ERROR: The ERROR state indicates that an unsupported request has been received or the API server is having problems.\nThe server will always follow an ERROR response by closing the connection."
      type: string
    filename_v1alpha1TagData:
      properties:
        source:
          $ref: '#/components/schemas/filename_v1alpha1TagSourceType'
        type:
          title: A grouping of related types of tags
          type: string
        value:
          title: The most specific part of the tag
          type: string
      type: object
    filename_v1alpha1RetrievalAudioInputAudioEncoding:
      description: "- UNSPECIFIED: Encoding not specified; default and returns an ERROR response.\n - LINEAR16: Uncompressed 16-bit signed little-endian samples (Linear PCM)."
      title: Audio encoding of the content in the message; must be one-channel (mono).
      type: string
    filename_v1alpha1RetrievalOption:
      properties:
        audio_output_enabled:
          description: Returns audio output when set to True; if no audio output is generated, responses include only text output; default is false.
          type: boolean
        max_outputs:
          description: Number of outputs to be returned; minimum is 3 (default), maximum is 10.
          format: int32
          type: integer
        context:
          properties: {}
          title: Additional context for the exchange input; improves response ranking quality.
          type: object
      title: Additional options for customizing the result of a Retrieval
      type: object
    filename_v1alpha1NormalizedRetrievalInput:
      properties:
        normalized_input_id:
          description: Unique identifier for the normalized input resource.
          type: string
        query:
          description: Original input query.
          type: string
        understood_tags:
          description: Tags detected from the query and used for filtering.
          items:
            $ref: '#/components/schemas/filename_v1alpha1TagData'
          type: array
      title: Post-processed version of the input
      type: object
    filename_v1alpha1GenerativeRetrievalResponseData:
      properties:
        text:
          description: A string containing the text output of the generative answer.
          type: string
        reference:
          description: Information about a specific reference made in the text output of the generative retrieval, including the start and end indices of the reference in the text, and the index of the retrieval output for the reference.
          items:
            $ref: '#/components/schemas/filename_v1alpha1RetrievalReference'
          type: array
        generative_retrieval_id:
          description: Unique identifier for the generative response object.
          type: string
        knowledge_domain_id:
          description: Unique identifier for the knowledge domain associated with the generative retrieval.
          type: string
        retrieval_id:
          description: Unique identifier for the response object.
          type: string
        collection_id:
          description: The collection, or index, that the exchange is performed against.
          type: string
      type: object
    filename_v1alpha1CreateGenerativeRetrievalRequest:
      description: CreateGenerativeRetrievalsRequest represents a request to create a new generative retrieval event.
      properties:
        input:
          $ref: '#/components/schemas/filename_v1alpha1CreateRetrievalRequest'
        temperature:
          description: Temperature 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; default value is 0, promoting deterministic and repetitive generative text.
          format: float
          type: number
        max_context_chunk_num:
          description: Maximum number of context chunks for a response; value must be greater than 0; default value is 3.
          format: int32
          type: integer
        min_context_chunk_score:
          description: Minimum score of context_chunk for a response; value must be between 0 and 1; default value is 0.55.
          format: float
          type: number
        context_chunk_beam_delta_cutoff:
          description: Maximum allowable answer in context score delta from the highest score to be considered when generating a response; value must be between 0 and 1; 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; value must be between 0 and 1; default value is 0.55.
          format: float
          type: number
        out_of_domain_score_threshold:
          description: Threshold of best answer score for which out of domain message should be returned as a final answer; value must be between 0 and 1; default value 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
    filename_v1alpha1RetrievalAudioInput:
      properties:
        audio_encoding:
          $ref: '#/components/schemas/filename_v1alpha1RetrievalAudioInputAudioEncoding'
        sample_rate_hertz:
          description: Sample rate in hertz of the audio data; only valid value is 16000, which must be explicitly stated by the client.
          format: int32
          type: integer
        content:
          description: Bytes of encoded audio data.
          format: byte
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
      title: Audio input for speech to text
      type: object
    filename_v1alpha1RetrievalData:
      properties:
        user_id:
          title: The identifier of the user that originally made the Retrieval
          type: string
        conversation_id:
          description: Unique identifier for conversations for subsequent calls; saved in the client and returned on the next request.
          type: string
        retrieval_id:
          description: Unique ID of the response item.
          type: string
        collection_id:
          description: Parent collection for the knowledge domain; autogenerated and not editable.
          type: string
        knowledge_domain_id:
          description: Unique identifier of the knowledge domain that supplied the exchange response.
          type: string
        normalized_input:
          $ref: '#/components/schemas/filename_v1alpha1NormalizedRetrievalInput'
        suggested_query:
          description: Spelling corrections, if any, or other suggestions found for the input query.
          items:
            type: string
          type: array
        outputs:
          description: List of outputs answering the question ported from retrieval result.
          items:
            $ref: '#/components/schemas/filename_v1alpha1RetrievalOutput'
          type: array
      title: A Retrieval is the primary object for getting content matched against the question asked in CreateRetrieval
      type: object
    filename_v1alpha1RetrievalOutput:
      properties:
        id:
          description: Unique identifier for the output resource.
          type: string
        answer_snippet:
          description: Best matching snippet displayed to the end-user
          type: string
        final_query:
          description: Specific matched query after synonym expansion and prior knowledge corrections.
          type: string
        context_chunk:
          description: Full surrounding text content for the matched text.
          type: string
        context_chunk_start_page:
          description: Page number where the answer in context starts in a document.
          format: int32
          type: integer
        context_chunk_end_page:
          description: Page number where the answer in context ends in a document.
          format: int32
          type: integer
        context_chunk_bbox:
          items:
            $ref: '#/components/schemas/filename_v1alpha1BoundingBox'
          description: Bounding boxes of answer in context; generally one response but can be multiple if the context chunk spans pages.
          type: array
        score:
          description: Approximate strength of the returned answer in context.
          format: float
          type: number
        answer_snippet_score:
          format: float
          description: Approximate gauge of how well the the answer snippet matched the query.
          type: number
        answer_snippet_start_index:
          description: Character index of the first occurrence of the answer text within the surrounding answer in context.
          format: int32
          type: integer
        answer_snippet_end_index:
          description: Character index of the last occurrence of the answer within the surrounding answer in context.
          format: int32
          type: integer
        answer_snippet_bbox:
          items:
            $ref: '#/components/schemas/filename_v1alpha1BoundingBox'
          title: Bounding boxes for each line of the text match.
          type: array
        audio:
          $ref: '#/components/schemas/filename_v1alpha1RetrievalAudioOutput'
        confidence_label:
          description: Answer confidence levels; used to categorize outputs.
          type: string
        tags:
          description: Tags associated with the output.
          items:
            $ref: '#/components/schemas/filename_v1alpha1TagData'
          type: array
        answer_type:
          $ref: '#/components/schemas/filename_RetrievalOutputAnswerType'
        verified_answer_id:
          description: Unique identifier of the verified answer; if the answer isn't verified this is unset.
          type: string
        video_time_offset_seconds:
          description: Length of time from the beginning of a in video (in seconds) until the short answer is found.
          format: int32
          type: integer
        content_group:
          $ref: '#/components/schemas/filename_v1alpha1ContentGroupSparse'
        content_metadata:
          $ref: '#/components/schemas/filename_v1alpha1ContentMetadata'
        context:
          $ref: '#/components/schemas/filename_v1alpha1RetrievalContext'
        answer_html:
          title: A marked up HTML version of the text_wordy/answer_in_context text
          type: string
      title: Each Retrieval output represents text matched in source content against the input
      type: object
    filename_v1alpha1GenerativeRetrievalConversationData:
      properties:
        data:
          $ref: '#/components/schemas/filename_v1alpha1GenerativeRetrievalResponseData'
        conversation_id:
          description: Unique identifier for conversations for subsequent calls; saved in the client and returned on the next request.
          type: string
      type: object
    filename_v1alpha1RetrievalContext:
      description: Additional context for the output.
      properties:
        augmentation:
          description: Predefined additional information provided with the source of this output.
          properties: {}
          type: object
      type: object
    filename_v1alpha1ContentMetadata:
      properties:
        content_id:
          description: Unique identifier for the content within the matching content groups.
          type: string
        content_display_name:
          description: Display name of the source file that includes the best sentence answer.
          type: string
        content_source_uri:
          description: Unique identifier for the source content that contains the answer.
          type: string
        content_origin_source_url:
          description: URL for the original source location of a document.
          type: string
        content_create_time:
          format: date-time
          title: Time of the initial content update.
          type: string
        content_update_time:
          format: date-time
          title: Time of the last update; 0 indicates updates have never been made.
          type: string
        image_uri:
          title: First page of the document where the answer was found.
          type: string
        hyperlinks:
          items:
            type: string
          title: Relevant links to the web-based document.
          type: array
        author:
          title: Name of the author who created the document.
          type: string
        author_id:
          title: Unique identifier for the author who created the document.
          type: string
        title:
          description: Name or title of the document; maximum size is 255 characters.
          type: string
        description:
          description: Summary of the document; maximum size is 1000 characters.
          type: string
        mime_type:
          title: Document media type.
          type: string
        additional_metadata:
          additionalProperties:
            properties: {}
            type: object
          title: Metadata captured when ingesting the document.
          type: object
      title: Additional metadata from the source content
      type: object
    filename_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
    filename_v1alpha1ResourceMetadata:
      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
    filename_RetrievalOutputAnswerType:
      default: UNSPECIFIED
      description: "- UNSPECIFIED: None\n - TEXT_EXCERPT: Default\n - FAQ: Answer comes from FAQ.\n - VA_PROMOTED: Promoted answer from existing content.\n - VA_CURATED: Verified answer created as standalone VA content.\n - BELOW_CONFIDENCE_THRESHOLD: Results scored below a minimum confidence threshold.\n - NO_ANSWER: No answer matched, or no permissions to see the matches; alternate answer supplied.\n - INTELLIGIBILITY_OUT_OF_SCOPE: Query is classified as gibberish and is not intelligible.\n - LANGUAGE_OUT_OF_SCOPE: Query is not in a supported language.\n - CONVERSATIONAL_OUT_OF_SCOPE: Query is classified as conversational."
      title: General source of the answer
      type: string
    filename_v1alpha1RetrievalAudioOutput:
      properties:
        audio_output_id:
          description: Unique identifier for the audio output resource.
          type: string
        audio_encoding:
          $ref: '#/components/schemas/filename_v1alpha1RetrievalAudioOutputAudioEncoding'
        sample_rate_hertz:
          description: Sample rate in hertz of the audio data; only valid value is 16000, which must be explicitly stated by the client.
          format: int32
          type: integer
        content:
          description: Bytes of encoded audio data.
          format: byte
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
      title: Audio output when answer is converted back to speech
      type: object
    filename_v1alpha1CreateRetrievalRequest:
      description: Message sent by the client for the create retrieval method.
      properties:
        conversation_id:
          description: Unique identifier for the conversation returned with the create retrieval response; leaving blank starts a new conversation on the request.
          type: string
        language_id:
          description: Language tags; default is en-US.
          type: string
        query:
          description: Input query used for retrieval.
          type: string
        audio:
          $ref: '#/components/schemas/filename_v1alpha1RetrievalAudioInput'
        options:
          $ref: '#/components/schemas/filename_v1alpha1RetrievalOption'
        filters:
          $ref: '#/components/schemas/filename_v1alpha1RetrievalFilter'
      type: object
    filename_v1alpha1GenerativeRetrievalSSEData:
      description: 'Important note: For forward compatibility, the client implementation should ignore states that are not relevant to them.'
      properties:
        metadata:
          $ref: '#/components/schemas/filename_v1alpha1ResourceMetadata'
        state:
          $ref: '#/components/schemas/filename_v1alpha1GenerativeRetrievalSSEDataState'
        input_text:
          description: Input text processed or interpreted by the LLM; may or may not equal to the query input text.
          type: string
        retrieval_data:
          $ref: '#/components/schemas/filename_v1alpha1RetrievalData'
        conversation_data:
          $ref: '#/components/schemas/filename_v1alpha1GenerativeRetrievalConversationData'
        error:
          $ref: '#/components/schemas/filename_googlerpcStatus'
      title: 'GenerativeRetrievalSSEData represents the data associated with a generative retrieval 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
    filename_v1alpha1GetGenerativeRetrievalResponse:
      properties:
        metadata:
          $ref: '#/components/schemas/filename_v1alpha1ResourceMetadata'
        data:
          $ref: '#/components/schemas/filename_v1alpha1GenerativeRetrievalResponseData'
      type: object
  securitySchemes:
    oauth2_token:
      description: The Pryon APIs are authenicated with an OAuth2 Bearer token.
      type: apiKey
      name: 'Authoriation: Bearer'
      in: header
x-tagGroups:
- name: Retrieval APIs
  tags:
  - Content Service
  - Exchange
  - Glossary