Generates a completion based on the input messages and retrieval chunks. If the 'stream' parameter is set to true, the response is returned as a stream of plain text (text/plain).
Required roles: All, App
## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/qaip/openapi.documented.yml post /completions openapi: 3.0.3 info: title: QAIP APIs version: 1.0.0 servers: - url: https://developer.qaip.com/api/v1 description: API base path security: - ApiKeyAuth: [] tags: - name: completions description: Generate completions - name: search description: Search content - name: extract description: Data extraction using LLM - name: tags description: List available tags - name: agent description: (Experimental) Agent operations - name: tag-source-groups description: Tag and source group associations - name: source-groups description: Source group (job) management and metadata - name: sources description: Sources management and metadata - name: local-file-groups description: Local file group management - name: secrets description: Secret management - name: google-drives description: Google Drive data source management - name: google-drive-settings description: Google Drive data source setting management - name: crawls description: Web crawl data source management - name: crawl-settings description: Web crawl setting management - name: githubs description: GitHub data source management - name: github-settings description: GitHub data source setting management - name: notions description: Notion data source management - name: notion-settings description: Notion data source setting management - name: authz-subject-attributes description: Authorization subject attribute management (admin only) paths: /completions: post: tags: - completions summary: Generate LLM completion description: >Generates a completion based on the input messages and retrieval chunks. If the 'stream' parameter is set to true, the response is returned as a stream of plain text (text/plain).
Required roles: All, App
operationId: completions requestBody: required: true content: application/json: schema: type: object required: - messages properties: messages: type: array description: The messages to generate completion for items: type: object required: - role - content properties: role: $ref: '#/components/schemas/MessageRole' content: type: string description: The content of the message stream: type: boolean description: > Whether to stream the response. If true, the response is sent as a stream using the 'text/plain' content type. default: false citation: type: boolean description: Whether to include citations in the response default: true grounding: type: boolean default: false description: > Whether to enable Gemini's Google Search grounding during answer generation. Only effective when the completion model is a Gemini model and the `gemini_grounding` feature is enabled on the server; otherwise this flag is ignored. tags: type: array description: target tag names to be obtained items: type: string tag_ids: type: array description: target tag IDs to be obtained items: type: string tag_filter_logic: $ref: '#/components/schemas/LogicalOperator' source_types: type: array items: $ref: '#/components/schemas/SourceType' file_types: type: array items: $ref: '#/components/schemas/FileType' date_from: type: integer description: Start date for content search (Unix timestamp in seconds) minimum: 1735639200 date_to: type: integer description: End date for content search (Unix timestamp in seconds) minimum: 1735639200 domains: type: array description: >- Array of domains to search within (supports partial matching) items: type: string metadata: $ref: '#/components/schemas/MetadataFilterGroup' source_metadata: $ref: '#/components/schemas/MetadataFilterGroup' description: >- Filter by individual source/file metadata from source_metadatas table chunk_metadata: $ref: '#/components/schemas/MetadataFilterGroup' description: Filter by chunk-level metadata from chunk_metadatas table use_postfilter: type: boolean default: false description: > Whether to bypass LanceDB prefilter and apply WHERE after the vector search (IVF_PQ) returns top-K. Significantly faster for broad filters that cover most of the table, but may return fewer than `limit` results when the hit rate is low. limit: type: integer description: >- Maximum number of chunks to retrieve as context for completion minimum: 1 maximum: 100 default: 10 authz_policy: type: string description: > (reserved for future use) Name of the registered authz policy to evaluate when retrieving context. Defaults to the reserved "default" policy when omitted. Ignored when authz is disabled. pattern: ^[a-z][a-z0-9_-]{0,63}$ example: external-chatbot principal_id: type: string description: > Identifier of the end-user (principal) on whose behalf this request is made. Used to look up the principal's authz subject attributes for policy evaluation. When omitted, subject attributes are empty (most restrictive). Ignored when authz is disabled. maxLength: 256 example: user-123 conversation_id: type: string description: > Conversation to append this turn to. When omitted, a new conversation is created server-side and its id is returned (response body for JSON, the X-Conversation-Id header for streaming). Pass it back on subsequent turns so the answer is persisted into the same conversation history tree. When set, the past conversation is rebuilt server-side from the stored tree, so only the latest user message in `messages` is used as the new input (earlier `messages` entries are ignored). Retrieval uses that latest question. example: 550e8400-e29b-41d4-a716-446655440000 parent_message_id: type: string description: > Id of the message node to branch this turn from (the parent of the new user message). When omitted, the turn continues from the conversation's current active leaf. Set it to fork a branch (e.g. editing an earlier question). Must belong to conversation_id. example: f47ac10b-58cc-4372-a567-0e02b2c3d479 regenerate: type: boolean description: > When true, the latest user message is NOT persisted again; instead a new assistant answer is created as a sibling under parent_message_id (which must reference an existing user message). Used to regenerate an answer. default: false truncation: type: string enum: - auto - disabled default: auto description: > How to handle a reconstructed conversation that exceeds the model's context budget (only relevant when conversation_id is set, i.e. history is rebuilt server-side). "auto": drop the oldest turns until it fits (the latest question is always kept). "disabled": return 400 if it does not fit. responses: '200': description: > Successful completion. If the 'stream' parameter is false, the response is returned as application/json. If the 'stream' parameter is true, the response is returned as a stream of plain text (text/plain). content: application/json: schema: type: object required: - created - choices properties: created: type: integer description: >- The Unix timestamp (in seconds) of when the completion was created example: 1677649420 conversation_id: type: string nullable: true description: > Target conversation id. For an existing conversation (conversation_id was supplied) it is always returned, even if this turn's answer was not persisted. For a new conversation it is null when nothing was persisted (e.g. no answer generated, or the history write failed). example: 550e8400-e29b-41d4-a716-446655440000 user_message_id: type: string nullable: true description: > Id of the persisted user message node for this turn. Null when the turn was not persisted. example: f47ac10b-58cc-4372-a567-0e02b2c3d479 assistant_message_id: type: string nullable: true description: > Id of the persisted assistant message node (the new active leaf). Null when no assistant node was persisted. example: 9b2e6f1a-3c4d-4e5f-8a9b-0c1d2e3f4a5b choices: type: array description: The completion choices generated by the model items: type: object required: - index - message - finish_reason properties: index: type: integer description: The index of this completion choice example: 0 message: type: object required: - role - content properties: role: type: string description: The role of the message sender enum: - assistant example: assistant content: type: string description: The content of the message example: Hello! How can I help you today? finish_reason: type: string description: The reason why the model stopped generating tokens example: stop citations: type: array description: Array of search results items: $ref: '#/components/schemas/Content' web_citations: type: array description: > Web sources from Gemini's Google Search grounding, returned separately from `citations`. Present only when grounding was enabled and the model used web results. items: $ref: '#/components/schemas/WebCitation' search_suggestion: type: string description: > Google Search Suggestions HTML (searchEntryPoint.renderedContent) from Gemini grounding. Per Google's "Grounding with Google Search" terms, clients MUST display this content as provided whenever it is present. Present only when grounding produced search suggestions. web_search_queries: type: array description: > The Google Search queries Gemini issued for grounding. Present only when grounding was used. items: type: string text/plain: schema: type: string description: > In streaming mode, the server sends plain text responses, not JSON objects. Each chunk is just plain text (e.g., part of a message). example: Hello! How can I help you today? '400': description: Bad Request - The request was malformed or invalid content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Too Many Requests - Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyAuth: [] x-codeSamples: - lang: Python source: |- import os from qaip import Qaip client = Qaip( api_key=os.environ.get("QAIP_API_KEY"), # This is the default and can be omitted ) response = client.completion( messages=[{ "content": "content", "role": "system", }], ) print(response.assistant_message_id) components: schemas: MessageRole: type: string description: The role of the message sender enum: - system - user - assistant LogicalOperator: type: string enum: - AND - OR default: OR description: Logical operator for combining filter conditions SourceType: type: string description: The type of the source enum: - crawl - local_file - google_drive - github - notion FileType: type: string description: The type of the source file enum: - html - pdf - ppt - pptx - pptm - doc - docx - docm - xls - xlsx - xlsm - md - txt - jsonl - png - jpg - webp - heic - heif - wav - mp3 - aiff - aac - m4a - ogg - flac - mp4 - mpg - mov - avi - flv - webm - wmv - 3gp - notion_page MetadataFilterGroup: type: object description: >- (reserved for future use) Filter group with nested structure. Supports combining filters with AND/OR logic. properties: logic: $ref: '#/components/schemas/LogicalOperator' filters: type: array description: Filters within this group (combined using the logic operator) items: $ref: '#/components/schemas/MetadataFilter' groups: type: array description: Nested subgroups items: $ref: '#/components/schemas/MetadataFilterGroup' maxItems: 10 Content: type: object required: - id - text - url - title - timestamp - file_type - page_number - source_type properties: id: type: string description: Content ID text: type: string description: Content chunk from the source url: type: string description: Source URL of the content title: type: string description: Title of the content or document timestamp: type: integer description: Unix timestamp when the content was indexed file_type: $ref: '#/components/schemas/FileType' page_number: type: integer description: >- Page number for paginated documents like PDFs. Set to 0 for sources without page numbers default: 0 source_type: $ref: '#/components/schemas/SourceType' source_id: type: string description: > Optional source ID for the original source. For crawl content, use this value with GET /sources/{source_id}/raw to download the stored crawl file content. For local_file content, use GET /sources/{source_id} for source details. keywords: type: array items: type: string WebCitation: type: object description: > A web source returned by Gemini's Google Search grounding. Distinct from Content (internal knowledge base citations); surfaced separately so clients can render web references apart from internal document citations. required: - url - title properties: url: type: string description: URL of the grounded web source title: type: string description: Title of the grounded web source Error: type: object required: - error properties: error: type: object required: - message - type properties: message: type: string description: Human-readable error message type: type: string description: Machine-readable error code MetadataFilter: type: object description: Metadata filter for filtering search results by key/value pairs required: - key - type - operator properties: key: type: string description: Metadata key val: description: >- Metadata value (string or number). This is optional since min/max can be used for range queries. type: type: string enum: - string - integer - float - date - datetime description: Data type of the metadata value operator: type: string enum: - eq - ne - gt - gte - lt - lte - between default: eq description: Comparison operator min: description: Minimum value for range queries (string or number) max: description: Maximum value for range queries (string or number) securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for authentication ````