Pryon Generative Retrieval API
The GenerativeRetrieval API from Pryon — 2 operation(s) for generativeretrieval.
OpenAPI Specification
openapi: 3.2.0
info:
title: Retrieval 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_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_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_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_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_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_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_v1alpha1GetGenerativeRetrievalResponse:
properties:
metadata:
$ref: '#/components/schemas/filename_v1alpha1ResourceMetadata'
data:
$ref: '#/components/schemas/filename_v1alpha1GenerativeRetrievalResponseData'
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_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_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_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_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_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_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_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_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_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_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_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_googlerpcStatus:
properties:
code:
format: int32
type: integer
message:
type: string
details:
items:
$ref: '#/components/schemas/filename_protobufAny'
type: array
type: object
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_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_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_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_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
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