> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.markup.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.markup.ai/_mcp/server.

# Create Style Agent Batch Files

POST https://api.markup.ai/style-agent/batch-files
Content-Type: multipart/form-data

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.

Reference: https://docs.markup.ai/developer-reference/api-reference/style-agent/create-style-agent-batch-files

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Headers

- `Idempotency-Key` (string, optional, nullable) — 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.

### Body (multipart/form-data)

This endpoint expects a multipart form with multiple files.

- `file_uploads` (files, required) — 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.
- `items` (string, optional) — 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.
- `defaults` (string, optional) — Optional JSON object of per-batch defaults applied to any item that omits the field.
- `webhook_url` (string, optional) — 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

### 202

Batch accepted

- `batch_id` (string, required)
- `segment_workflow_id` (string, required)
- `status` (enum, required) — 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.
  - Allowed values: `running`, `completed`
- `item_count` (integer, required)
- `created_at` (datetime, required)
- `items` (list of BatchItemResponse, required)

## Errors

### 401 Unauthorized Error

Authentication failed or no valid API key provided.

- `detail` (string, required) — A description of the error that occurred.
- `status` (integer, required) — The HTTP status code generated by the server for this issue
- `request_id` (string, required) — A unique ID associated with the HTTP request.

### 403 Forbidden Error

Forbidden

- `detail` (string, required) — A description of the error that occurred.
- `status` (integer, required) — The HTTP status code generated by the server for this issue
- `request_id` (string, required) — A unique ID associated with the HTTP request.

### 404 Not Found Error

Style guide not found, or agent unavailable

- `any`

### 409 Conflict Error

Idempotency-Key reused with a different payload

- `any`

### 413 Content Too Large Error

Uploads exceed the per-file or per-request size limit

- `any`

### 422 Unprocessable Entity Error

Invalid input for one or more items

- `any`

### 500 Internal Server Error

Internal Server Error

- `detail` (string, required) — A description of the error that occurred.
- `status` (integer, required) — The HTTP status code generated by the server for this issue
- `request_id` (string, required) — A unique ID associated with the HTTP request.

## Types

### BatchItemResponse

Per-item entry in a batch response (no full result — fetch by workflow_id, D5).

- `item_id` (string, required)
- `workflow_id` (string, required)
- `status` (enum, required) — Per-document status within a batch, cached from the child workflow.
  - Allowed values: `pending`, `running`, `completed`, `failed`
- `document_ref` (string, optional, nullable)
- `error_category` (enum, optional, nullable) — Why a batch item failed (D7): a bad request vs. a processing/system fault.
  - Allowed values: `input`, `processing`