> 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.

# Append Style Agent Batch Files

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

Append up to 20 more uploaded documents to a batch that is still processing.

The file-upload form of `POST /style-agent/batch/{batch_id}/items`; a
batch may mix the two freely. Rejected with 409 once the batch is sealed
(1000 documents reached, or every document has finished) — create a new
batch instead. Send an `Idempotency-Key` header to make retries safe.

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

## Authentication

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

## Request

### Path parameters

- `batch_id` (string, required)

### 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.

## Response

### 202

Documents appended

- `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

Batch not found, style guide not found, or agent unavailable

- `any`

### 409 Conflict Error

Batch sealed or over the 1000-document limit, or 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`