---
title: "Append Style Agent Batch Items"
method: POST
path: "/style-agent/batch/{batch_id}/items"
tags: ["styleAgent"]
---

# Append Style Agent Batch Items

`POST /style-agent/batch/{batch_id}/items`

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

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: the same key + payload
replays the original 202 instead of appending the documents again.

## Path parameters

- `batch_id` string, required

## Headers

- `Authorization` string, required
- `Idempotency-Key` string, nullable

## Request body

- AppendItemsRequest
  - `items` BatchItemRequest[], required
    - `text` string, required
    - `document_ref` string, nullable — Caller-provided document identifier.
    - `style_guide_id` string, nullable — Style guide to check against (overrides defaults).
    - `content_profile_id` string, nullable
    - `domain_ids` string[], nullable
    - `url` string, nullable
    - `document_name` string, nullable
    - `author` string, nullable — Who this document's check is credited to (D16). A batch check counts as authoring activity for its content's author; supply that identity here. When omitted, the check is credited to the batch's runner.
  - `defaults` BatchDefaults — Optional per-batch defaults applied to any item that omits the field.
    - `style_guide_id` string, nullable
    - `content_profile_id` string, nullable
    - `domain_ids` string[], nullable

## Response `202`

Documents appended

- BatchAcceptedResponse — 202 body for create/append.
  - `batch_id` string, required
  - `segment_workflow_id` string, required
  - `status` 'running' | 'completed', 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.
  - `item_count` integer, required
  - `created_at` string, date-time, required
  - `items` BatchItemResponse[], required
    - `item_id` string, required
    - `document_ref` string, nullable
    - `workflow_id` string, required
    - `status` 'pending' | 'running' | 'completed' | 'failed', required — Per-document status within a batch, cached from the child workflow.
    - `error_category` 'input' | 'processing' — Why a batch item failed (D7): a bad request vs. a processing/system fault.

## Other responses

- `401` — Authentication failed or no valid API key provided.
- `403` — Forbidden
- `404` — Batch not found
- `409` — Batch sealed or over the 1000-document limit, or Idempotency-Key reused with a different payload
- `413` — Request payload exceeds the per-request size limit
- `422` — Invalid input for one or more items
- `500` — Internal Server Error

## Changes

- **2026-08-21** `65e1214d0bbf` — 12 breaking, 4 warning
  - for the `header` request parameter `Idempotency-Key`, the minLength was increased from `0` to `1`
  - the `defaults/oneOf[subschema #1: BatchDefaults]/content_profile_id` request property's minLength was increased from `0` to `1`
  - the `defaults/oneOf[subschema #1: BatchDefaults]/domain_ids/items/` request property's minLength was increased from `0` to `1`
  - the `defaults/oneOf[subschema #1: BatchDefaults]/style_guide_id` request property's minLength was increased from `0` to `1`
  - …12 more
- **2026-08-14** `9f470199d1d1` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/markup/apis/api-reference/changes/style-agent/batch/:batch_id/items/post.md)

---

[API](https://skmtc.dev/markup/apis/api-reference.md) · [All operations](https://skmtc.dev/markup/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/markup/api-reference/revisions/65e1214d0bbf/schema)