> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Process batch document update
> Processes a batch update for multiple document families in a single request. Supports uploading binary files, applying labels, updating notes, and deleting documents. Use multipart/form-data for file uploads or application/json for metadata-only updates.
## Task status in the response
Send the task's status as `statusSlug` on the `task` object. The task echoed back in the response carries it under the same name, matching the Task model everywhere else in the API, so a client can apply the returned task directly to its local copy.
```json theme={null}
{
"task": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"statusSlug": "reviewed",
"changeSequence": 42
}
}
```
The legacy `statusId` key is no longer emitted in the batch response. Integrations that read the task status from this endpoint must read `statusSlug`.
## Completing a task with a discarded save
When the batch moves the task to a status of type `DONE`, the platform first checks the task's documents. If the most recent saved changes for one of them were discarded server-side and never redone, the request is refused with `409 Conflict` and no part of the batch is applied — the status change, the queued document uploads, the label changes and the deletes are all rolled back together.
The message names the affected documents by path (or by ID when a document has no path):
```json theme={null}
{
"code": "CONFLICT",
"message": "Cannot complete this task: the most recent saved changes for invoices/2026-08/inv-1042.pdf were not applied to the stored document (the save failed server-side). Reopen the document, redo the changes, and save again before completing."
}
```
To clear the block, reopen each document the message names, redo the changes, and save again. A successful re-save — or any full-document save — releases it and the batch completes normally.
Uploads sent in the same batch as the completion are queued before the check runs, so saving and completing in one request is not blocked by that request's own save. Only the latest save per document counts, so a failure that has already been redone and saved does not block completion. Batches that leave the task's status unchanged, or move it to a status of any other type, are unaffected.
This endpoint also returns `409 Conflict` for a stale `changeSequence` on the task; the two cases share the `CONFLICT` code and are distinguished by the message.
## OpenAPI
````yaml post /api/batch-update
openapi: 3.0.1
info:
title: Kodexa AI
description: >-
The Kodexa platform API provides programmatic access to document processing,
intelligent automation, and data extraction capabilities. Use this API to
manage organizations, projects, document stores, taxonomies, assistants, and
processing pipelines. All endpoints require authentication via API key,
Bearer token, or Basic auth.
version: 8.0.0
license:
name: Commercial
url: https://kodexa.ai
servers:
- url: https://platform.kodexa.ai
description: Production
- url: http://localhost:8080
description: Local development
security:
- x-api-key: []
- bearerAuth: []
tags:
- name: AI Gateway
- name: AccessTokens
description: Manage API access tokens for programmatic authentication.
- name: Account
description: Account management endpoints for the authenticated user.
- name: Activities
- name: ActivityDocumentFamilies
- name: ActivityPlans
- name: Agent Runtimes
description: Manage agent runtime definitions backed by AWS Bedrock AgentCore.
- name: Agent Sessions
description: View and manage stateful conversation sessions within agent runtimes.
- name: Agents
description: Manage agents — instantiated agent runtimes within an org+project.
- name: Analytics
- name: Applied Knowledge
description: Manage applied knowledge instances used during document processing.
- name: Applied Knowledge Sets
description: Manage applied knowledge set configurations.
- name: Assistants
description: Manage AI assistants that process and analyze documents within a project.
- name: Batch Updates
description: Batch document update operations for efficient bulk processing.
- name: Channel
description: Manage messaging channels for real-time communication within the platform.
- name: Channel Types
- name: Content Exception
description: View and manage content exceptions that occur during document processing.
- name: Content Object
description: >-
Manage content objects — individual files or processing results within a
document family.
- name: Credit Transactions
description: View and manage credit transactions for organization billing.
- name: Data Definitions
description: >-
Manage data definitions (taxonomies) that define document structure and
extraction rules.
- name: Data Forms
description: Manage data form definitions for structured data capture from documents.
- name: Data Stores
description: Manage data stores for structured data storage.
- name: Document Assignments
description: Manage document assignments linking document families to users for review.
- name: Document Family Statistics
description: View statistics about document families including processing metrics.
- name: Document Statuses
description: >-
Manage document status definitions for tracking document processing
states.
- name: Document Stores
description: >-
Manage document stores — containers for organizing and processing
documents within a project.
- name: Document Transitions
description: Track state transitions of documents through processing stages.
- name: DocumentFamilies
description: >-
Manage document families — groups of related content objects representing
a single logical document.
- name: Events
description: >-
Manage and publish platform events for real-time notifications and
integrations.
- name: Execution Slices
description: View execution slice details within pipeline executions.
- name: Executions
description: View and manage processing execution records.
- name: Intakes
description: >-
Manage intake configurations for ingesting documents from external
sources.
- name: Knowledge Clause Features
description: Manage features within knowledge clauses.
- name: Knowledge Clauses
description: Manage knowledge clauses within knowledge items.
- name: Knowledge Feature Types
description: Manage knowledge feature type definitions.
- name: Knowledge Features
description: >-
Manage knowledge features representing specific data points within
knowledge items.
- name: Knowledge Item Types
description: Manage knowledge item type definitions.
- name: Knowledge Items
description: Manage individual knowledge items within knowledge sets.
- name: Knowledge Set Snapshots
description: Manage snapshots of knowledge sets for versioning and comparison.
- name: Knowledge Set Sources
description: Manage source references for knowledge sets.
- name: Knowledge Sets
description: >-
Manage knowledge sets — collections of extracted knowledge used for
AI-assisted processing.
- name: Labels
description: >-
Manage labels used for categorizing and tagging resources within an
organization.
- name: Linked Deltas
description: Manage linked deltas representing changes between document versions.
- name: Messages
description: Manage messages within channels.
- name: Model Costs
- name: Module Runtimes
description: Manage module runtime definitions within the orchestrator.
- name: Modules
- name: Orchestrator Modules
description: Manage processing modules for orchestrator pipelines.
- name: Organizations
description: >-
Manage organizations — the top-level tenant in Kodexa. All projects,
stores, and resources belong to an organization.
- name: Permissions
- name: Platform Configuration
description: Manage platform-wide configuration settings.
- name: Platform Overview
description: Platform configuration and overview endpoints.
- name: Product Groups
description: Manage product groups that bundle related products together.
- name: Product Overview
description: Browse and manage products available on the Kodexa platform.
- name: Product Subscriptions
description: Manage product subscriptions linking organizations to products.
- name: ProductProjectTemplates
description: >-
Manage product project templates that define default project
configurations.
- name: Project Resources
- name: Project Status
description: Manage project status definitions for tracking project lifecycle.
- name: Project Templates
description: Manage project templates that define reusable project configurations.
- name: Projects
description: >-
Manage projects within an organization. Projects group related document
stores, assistants, tasks, and processing pipelines.
- name: Prompts
description: Manage prompt templates used by AI assistants for document processing.
- name: Purge Items
description: Manage purge items for scheduled content cleanup.
- name: Recent Executions
description: View recent execution history for document processing.
- name: Resource Resolution
- name: Role Permissions
- name: Roles
- name: Service Bridges
- name: Sessions
description: Manage processing sessions for document operations.
- name: Step Executions
description: View step-level execution details within pipeline executions.
- name: Tag Metadata
description: Manage tag metadata definitions for document labeling and categorization.
- name: Task Groups
- name: Task Statuses
description: Manage task status definitions for tracking task workflow states.
- name: TaskActivity
description: Track activity history on tasks, including status changes and comments.
- name: TaskDocumentFamilies
description: Manage the association between tasks and document families.
- name: TaskGroupHistory
- name: TaskTemplates
description: Manage task templates that define reusable task configurations.
- name: Tasks
description: >-
Manage tasks for document review workflows. Tasks have assignees,
statuses, due dates, and can contain document families.
- name: Team Members
description: Manage team membership assignments.
- name: Team Org Assignments
- name: Team Project Assignments
- name: Teams
description: Manage teams for collaborative access control within projects.
- name: Triggers
- name: Users
description: Manage platform user accounts.
- name: Workspaces
description: Manage workspaces for organizing project resources.
externalDocs:
description: Kodexa Developer Documentation
url: https://developer.kodexa.ai
paths:
/api/batch-update:
post:
tags:
- Batch Updates
summary: Process batch document update
description: >-
Processes a batch update for multiple document families in a single
request. Supports uploading binary files, applying labels, updating
notes, and deleting documents. Use multipart/form-data for file uploads
or application/json for metadata-only updates.
operationId: batchUpdateProcessBatchUpdateWithBinaries
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchUpdate'
multipart/form-data:
schema:
type: object
properties:
files:
type: array
items:
type: string
format: binary
description: Binary files to upload as content objects.
metadata:
$ref: '#/components/schemas/BatchUpdate'
description: Batch update metadata describing the operations to perform.
responses:
'200':
description: Batch update result
content:
application/json:
schema:
$ref: '#/components/schemas/BatchUpdateResponse'
'400':
description: Bad Request — the request body or parameters are invalid.
'401':
description: Unauthorized — authentication is required.
'403':
description: Forbidden — the authenticated user does not have permission.
components:
schemas:
BatchUpdate:
type: object
properties:
contentObjectUploads:
type: object
properties:
uploads:
type: array
items:
type: object
properties:
documentFamilyId:
type: string
description: ID of the target document family.
fileIndex:
type: integer
format: int32
description: Index of the file in the multipart upload (0-indexed).
fileName:
type: string
description: Name of the uploaded file.
uploadType:
type: string
description: >-
Type of upload: 'DELTA' (queue for background application)
or 'FULL_DOCUMENT' (replace entire content). Defaults to
DELTA.
enum:
- DELTA
- FULL_DOCUMENT
description: List of file upload specifications.
description: Content object file uploads to add to document families.
deletes:
type: object
properties:
documentFamilyIds:
type: array
items:
type: string
description: IDs of document families to delete.
description: Document families to delete.
documentFamilyIds:
type: array
items:
type: string
description: IDs of document families to include in the batch.
labelUpdates:
type: object
properties:
newLabels:
type: array
items:
type: object
description: Labels to add.
removedLabels:
type: array
items:
type: object
description: Labels to remove.
description: Label additions and removals.
projectId:
type: string
description: ID of the project containing the document families.
task:
type: object
description: Optional task data to associate with the batch update.
userWorkSession:
type: object
properties:
activeDurationMs:
type: integer
format: int64
description: >-
Client-computed active/engaged duration in milliseconds —
cumulative time since startedAt during which the user had recent
input AND the tab was visible AND the window was focused.
Measured on a monotonic clock. Distinct from wall clock.
Recorded alongside the wall-clock duration for engagement
analytics.
clientNow:
type: string
format: date-time
description: >-
Client wall-clock timestamp captured when the request payload
was built. The server subtracts its receive time to estimate
this client's clock offset (positive = client ahead), enabling
per-user skew monitoring and de-skew of legacy timings.
elapsedMs:
type: integer
format: int64
description: >-
Client-measured session wall-clock in milliseconds on a
MONOTONIC clock (performance.now delta since task open). Immune
to client wall-clock skew; when present it is the authoritative
session duration downstream, replacing the cross-clock
subtraction endedAt - startedAt.
startedAt:
type: string
format: date-time
description: >-
ISO-8601 timestamp when the user opened the task in the UI.
Client wall-clock; retained for session identity and skew
diagnostics, but no longer the preferred wall-clock basis — see
elapsedMs.
description: >-
Optional client-supplied work-session context. The UI captures
startedAt when the user opens a task and sends it back on save so
the server can record how long the user spent on this work for
time-allocation analytics.
description: >-
A batch update request containing multiple document operations to be
processed atomically.
BatchUpdateResponse:
type: object
properties:
contentObjectUpdates:
type: array
items:
type: object
properties:
changeSequence:
type: integer
format: int32
description: Updated change sequence number.
contentObject:
$ref: '#/components/schemas/BatchUpdateContentObject'
documentFamily:
type: object
description: Updated document family data on success.
documentFamilyId:
type: string
description: ID of the target document family.
error:
type: string
description: Error message on failure.
linkedDeltaId:
type: string
description: ID of the created linked delta (DELTA uploads only).
success:
type: boolean
description: Whether the upload succeeded.
description: Results for each content object upload.
task:
type: object
description: Updated task data, if a task was included in the batch.
description: >-
Response from a batch update operation, containing results for each
document family.
BatchUpdateContentObject:
type: object
properties:
changeSequence:
type: integer
format: int32
description: Content object change sequence after this save.
id:
type: string
description: ID of the content object the upload was applied to.
description: >-
Post-save state of a content object returned from a batch update.
Clients use changeSequence to advance their polling baseline past their
own save so it is not detected as an external change.
securitySchemes:
x-api-key:
type: apiKey
name: x-api-key
in: header
description: >-
API key for authentication. Create one from the Kodexa platform UI under
Settings > Access Tokens.
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT Bearer token obtained from the authentication provider.
````