Interface BulkIngestionContext

The id of the context. Optional: when omitted, the server generates one and rejects the upload if another context in the knowledge base already holds identical content (content-level dedup). Provide an explicit id to address a specific context — that overwrites it unconditionally and allows duplicate content across different ids, exactly as the synchronous upsertContexts treats a supplied id. Must be unique within one request (each staged context becomes one per-file row keyed by this id), at most 512 UTF-8 bytes of letters, digits, _, ., :, @ or - only, and the overwrite lands asynchronously when the job finalizes the file.

Whether Squid discards a file context's downloadable original once it is extracted (the extracted text and images are stored either way); mirrors AiKnowledgeBaseFileContextRequest.discardOriginalFile, with the same consequences. Ignored for a text context.

Whether to extract images: inline markdown/HTML images for text contexts, embedded images for files.

Hint about a text context's format; only meaningful for type: 'text'.

Minimum width/height in pixels for an extracted image to be kept; mirrors the sync request's field of the same name. Smaller images are skipped, and an inline markdown/HTML image below it keeps its raw reference in the text.

Optional metadata associated with the context item; mirrors BaseAiKnowledgeBaseContextRequest.metadata. Squid-reserved keys are stripped server-side, and values are validated/normalized against the target knowledge base's metadataFields schema when one is declared.

The RAG type and chunk overlap this context is chunked and indexed with; mirrors the sync request's options, with the same defaults (the knowledge base's ragType, and the overlap that type implies). chunkOverlap must be a number below the 4,000-character chunk size.

The preferred method for extracting data from a file context; mirrors the sync lane's field of the same name, so a caller's choice survives whichever lane a deployment routes the upload through.

Access scopes granting read access to this context, stamped onto every chunk it produces when the job finalizes; mirrors BaseAiKnowledgeBaseContextRequest.scopes, with the same semantics: omitted keeps whatever scopes the context already had, an empty array makes it visible to every caller. On a knowledge base with accessControl.mode: 'enforced', a context whose scopes resolve to nothing at finalize is stamped unreadable rather than public.

Key returned by bulk/createUploadUrls; the server ingests the staged object as this context's file. Mutually exclusive with a positional multipart file.

The text content to stage; required for type: 'text'.

Title for a text context (required); optional display title for a file context.

'text' (the default) stages a text context; 'file' consumes the next uploaded file positionally.