Skip to main content
POST
Reprocess BatchDocuments against a different StructVersion
Re-extracts selected (or all non-terminal) documents, optionally against another published version. Each completed file is a new batch page 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

​
batch_id
integer
required

Body

application/json

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

Resets the extraction state of one or more BatchDocuments and requeues them for processing against a different (newer or older) StructVersion. Each affected doc is treated as a brand-new extraction — its ChatAttachment.extraction_result and ChatAttachment.extraction_struct_version are cleared so the next Lynx call starts from a clean slate.

Fields: version_number: Target StructVersion.version_number (must belong to the batch's parent struct, must NOT be deprecated). document_ids: Optional list of BatchDocument PKs to reprocess. When omitted (or empty), every doc in the batch is reprocessed. Subset semantics let the user re-extract a single misbehaving doc without re-running the whole batch (saves credits). failed_only: When True, additionally restrict the reprocess scope to BatchDocument rows in the FAILED state. Combines with document_ids (intersection) when both are supplied. Added in Task 7b (extraction-failure-surfacing) so users can recover the ~234 historical broken docs that the Task 6 backfill flips from COMPLETED to FAILED — per-row reprocess at that scale is impractical.

​
version_number
integer
required
Required range: x >= 1
​
document_ids
integer[]

Optional list of BatchDocument PKs to reprocess. Omit (or send an empty list) to reprocess every doc in the batch.

Maximum array length: 1024
Required range: x >= 1
​
failed_only
boolean
default:false

When true, restrict the reprocess scope to FAILED docs only. Intersects with document_ids when both are supplied — useful for batch-scale recovery after the extraction-status backfill flips historically broken docs to FAILED.

Response

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

Fields: batch: The updated parent batch (status flipped to PROCESSING when any doc was reset). reprocessed_doc_count: Number of BatchDocuments whose extraction state was actually cleared. Zero when document_ids matched no rows (still 200 — the request was valid, it just had no effect). estimated_credit_cost: Best-effort millicredit estimate for the reprocess job. Computed up-front from per-doc page counts so the SPA can render a "this will cost ~X credits" confirmation before the user clicks confirm. The actual deduction happens inside process_batch when each doc finishes.

​
batch
object
required

Compact projection of a Batch row for responses that need to echo the parent batch state alongside per-row payloads.

Currently used by BatchReprocessResponse so the SPA can update its batch header (status pill, default version chip) without a follow-up GET.

​
reprocessed_doc_count
integer
required
​
estimated_credit_cost
integer
required

Estimated millicredit cost across all reprocessed docs (page_count * EXTRACT_MILLICREDITS_PER_PAGE). Informational.