Skip to main content
POST
Python

Authorizations

x-api-key
string
header
required

API key for authentication

Body

application/json
messages
object[]
required

The messages to generate completion for

stream
boolean
default:false

Whether to stream the response. If true, the response is sent as a stream using the 'text/plain' content type.

citation
boolean
default:true

Whether to include citations in the response

grounding
boolean
default:false

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
string[]

target tag names to be obtained

tag_ids
string[]

target tag IDs to be obtained

tag_filter_logic
enum<string>
default:OR

Logical operator for combining filter conditions

Available options:
AND,
OR
source_types
enum<string>[]

The type of the source

Available options:
crawl,
local_file,
google_drive,
github,
notion
file_types
enum<string>[]

The type of the source file

Available options:
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
date_from
integer

Start date for content search (Unix timestamp in seconds)

Required range: x >= 1735639200
date_to
integer

End date for content search (Unix timestamp in seconds)

Required range: x >= 1735639200
domains
string[]

Array of domains to search within (supports partial matching)

metadata
object

(reserved for future use) Filter group with nested structure. Supports combining filters with AND/OR logic.

source_metadata
object

Filter by individual source/file metadata from source_metadatas table

chunk_metadata
object

Filter by chunk-level metadata from chunk_metadatas table

use_postfilter
boolean
default:false

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
integer
default:10

Maximum number of chunks to retrieve as context for completion

Required range: 1 <= x <= 100
authz_policy
string

(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
string

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.

Maximum string length: 256
Example:

"user-123"

conversation_id
string

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
string

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
boolean
default:false

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.

truncation
enum<string>
default:auto

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.

Available options:
auto,
disabled

Response

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).

created
integer
required

The Unix timestamp (in seconds) of when the completion was created

Example:

1677649420

choices
object[]
required

The completion choices generated by the model

conversation_id
string | null

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
string | null

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
string | null

Id of the persisted assistant message node (the new active leaf). Null when no assistant node was persisted.

Example:

"9b2e6f1a-3c4d-4e5f-8a9b-0c1d2e3f4a5b"