Create Style Agent Batch Files
Create a style-agent batch from up to 20 uploaded documents.
Accepts PDF, Word (.docx), HTML, XML (including DITA), Markdown, and
plain-text files. Each file is forwarded to the language service
unchanged — it extracts the text — so every check runs against the
document as submitted, exactly as POST /style-agent/run-file does for
a single document.
Per-item metadata is optional: send an items JSON array positionally
aligned with the files to set document_ref, author or a per-item
style guide. Omit it and every file is checked using the batch defaults,
with its filename used as the document name.
Behaves like POST /style-agent/batch otherwise: returns 202 with a
batch_id to poll at GET /style-agent/batch/{id}, and more documents
can be appended while it runs — as files via
POST /style-agent/batch/{id}/items-files or as text via
POST /style-agent/batch/{id}/items.
Issue positions index the text the language service extracted, not the bytes
you uploaded; use each issue’s context_surface to locate it in the
original document.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Headers
Optional client-generated key making this submission idempotent: a retry with the same key and payload returns the original accepted response instead of submitting the documents again. Reusing a key with a different payload returns 409.
Request
The documents to check, one file per batch item. Text (.txt), Markdown (.md), HTML (.html, .htm), XML including DITA (.xml, .dita), Word (.docx), and PDF (.pdf) files are accepted. Content is analyzed in the format it is detected as, whatever the extension: a .txt file that contains HTML is checked as HTML. For plain-text, HTML, and XML files, issue positions are offsets into the text of the file you uploaded, counted in UTF-16 code units. Size limits apply per file and to the request as a whole; exceeding either returns 413 naming the limit.
Optional JSON array of per-item metadata, positionally aligned with the uploaded files: entry i describes file i. Each entry accepts the same fields as a text batch item minus ‘text’. Omit it (or send it empty) to check every file using only the batch defaults. When present, its length must equal the number of uploaded files.
Optional JSON object of per-batch defaults applied to any item that omits the field.
Notified when the batch reaches a terminal state (D5). Delivery is bounded best-effort, not guaranteed: a failed POST is retried with backoff for roughly two hours and then abandoned, so this endpoint may be called zero times or more than once. GET /style-agent/batch/{batch_id} is authoritative — poll it if the notification has not arrived. Deduplicate on the payload’s batch_id: a batch has exactly one completion event, so batch_id is its stable event id.
Response
Lifecycle of a style-agent batch (see design-docs/style-agent-batch-checking.md).
A batch is running while any item is non-terminal; it becomes
completed (and sealed) once every item reaches a terminal state.