Skip to main content
POST
Add existing library documents to a batch
Attaches existing library documents and enqueues extraction at the batch page rate. Destination must not be canceled or a schema-test batch.

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

batch_id
integer
required

Body

application/json

Body for POST /api/v2/batches/{batch_id}/documents/.

Adds existing library documents (referenced by ChatAttachment.pk) to a batch. The batch's parent struct is implicit via Batch.default_struct_version — every per-doc version override must refer to the same struct.

Fields: document_ids: ChatAttachment PKs of docs in the user's library to attach to the batch. At least one is required. Order is preserved when assigning BatchDocument.processing_order. version_number: Optional override for the batch's default_struct_version for all added docs in this request. None means "use the batch's current default version". per_doc_versions: Optional fine-grained per-doc override map {document_id: version_number}. Keys must be a subset of document_ids. A doc id present in this map takes precedence over the request-level version_number.

document_ids
integer[]
required

ChatAttachment PKs of library docs to add to the batch.

Maximum array length: 1024
Required range: x >= 1
version_number
integer | null

Override version number applied to every added doc unless a per-doc override is set. Defaults to the batch's default_struct_version.

Required range: x >= 1
per_doc_versions
object

Map of {document_id: version_number} overriding the request-level version_number for individual docs.

Response

Response shape for POST /api/v2/batches/{batch_id}/documents/.

added lists the new BatchDocument rows in creation order. skipped lists docs that were not added with a human-readable reason — the request as a whole still returns 201.

added
object[]
required
skipped
object[]
required