Skip to main content
POST
Attach a batch to a chat as LLM context
Adds a visible batch as chat context. The grid is rebuilt on the next turn — no sync step. Attaching is free; the next user message is the chat charge.

Authorizations

​
Authorization
string
header
required

Organisation API key from Settings → API / /api/keys/. The secret is shown once. Send Authorization: Bearer sk-abacus-…. One active key per organisation. Ingest (/api/v2/ingest/*) refuses API keys — that surface is Auth0-only with ingest:read / ingest:write scopes.

Path Parameters

​
thread_id
string
required

Body

application/json

Body for POST /api/v2/chats/<thread_id>/batch-attachments/.

Fields: batch_id: PK of the Batch to attach. The view validates that the batch is visible to the request user via :func:documents.views._visible_batch_qs (shared batches via an approved org-library or active direct-share acceptance count as visible). context_mode: Render mode for BatchExtractionProvider. Defaults to "full" (entire effective grid; batches over the size limit still downshift to a summary). "summary" renders schema + a small row sample + a pointer to the query_batch_data SQL tool; "schema_only" renders schema + pointer with no rows. All three modes are honored at render time (AD-351 DuckDB batch analytics).

​
batch_id
integer
required

PK of the Batch to attach to this chat.

Required range: x >= 1
​
context_mode
enum<string>
default:full

Render mode for BatchExtractionProvider. 'full' (default) renders the entire grid into chat context (batches over the size limit still downshift to a summary); 'summary' renders schema + a small row sample + a query_batch_data SQL pointer; 'schema_only' renders schema + pointer with no rows.

  • full - full
  • summary - summary
  • schema_only - schema_only
Available options:
full,
summary,
schema_only

Response

Response shape for chat <-> batch attachment endpoints.

Surfaces enough metadata for the SPA's "Attached batches" panel to render without a follow-up /api/v2/batches/ lookup: batch_name, batch_status, the attaching user's email, and the render mode.

The model docstring on ChatBatchAttachment documents the unlink semantics -- the join row CASCADE-deletes with chat or batch but never deletes the chat/batch itself, so this serializer's view of batch is always live.

​
id
integer
required
read-only
​
batch_id
integer
required
read-only
​
batch_name
string
required
read-only
​
batch_status
string
required
read-only
​
attached_at
string<date-time>
required
read-only
​
attached_by_email
string | null
required
read-only

Surface the attaching user's email or None if user was deleted.

attached_by is SET_NULL on user delete -- we keep the join row alive even after the user is gone, so this returns None when the attacher account no longer exists.

​
context_mode
string
required
read-only

Render mode for BatchExtractionProvider. 'full' renders the entire grid (batches over the size limit still downshift to summary); 'summary' renders schema + a small sample + a query_batch_data SQL pointer; 'schema_only' renders schema + pointer with no rows.