Process batch document update
curl --request POST \
--url https://platform.kodexa.ai/api/batch-update \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"contentObjectUploads": {
"uploads": [
{
"documentFamilyId": "<string>",
"fileIndex": 123,
"fileName": "<string>"
}
]
},
"deletes": {
"documentFamilyIds": [
"<string>"
]
},
"documentFamilyIds": [
"<string>"
],
"labelUpdates": {
"newLabels": [
{}
],
"removedLabels": [
{}
]
},
"projectId": "<string>",
"task": {},
"userWorkSession": {
"activeDurationMs": 123,
"clientNow": "2023-11-07T05:31:56Z",
"elapsedMs": 123,
"startedAt": "2023-11-07T05:31:56Z"
}
}
'import requests
url = "https://platform.kodexa.ai/api/batch-update"
payload = {
"contentObjectUploads": { "uploads": [
{
"documentFamilyId": "<string>",
"fileIndex": 123,
"fileName": "<string>"
}
] },
"deletes": { "documentFamilyIds": ["<string>"] },
"documentFamilyIds": ["<string>"],
"labelUpdates": {
"newLabels": [{}],
"removedLabels": [{}]
},
"projectId": "<string>",
"task": {},
"userWorkSession": {
"activeDurationMs": 123,
"clientNow": "2023-11-07T05:31:56Z",
"elapsedMs": 123,
"startedAt": "2023-11-07T05:31:56Z"
}
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
contentObjectUploads: {
uploads: [{documentFamilyId: '<string>', fileIndex: 123, fileName: '<string>'}]
},
deletes: {documentFamilyIds: ['<string>']},
documentFamilyIds: ['<string>'],
labelUpdates: {newLabels: [{}], removedLabels: [{}]},
projectId: '<string>',
task: {},
userWorkSession: {
activeDurationMs: 123,
clientNow: '2023-11-07T05:31:56Z',
elapsedMs: 123,
startedAt: '2023-11-07T05:31:56Z'
}
})
};
fetch('https://platform.kodexa.ai/api/batch-update', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://platform.kodexa.ai/api/batch-update",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'contentObjectUploads' => [
'uploads' => [
[
'documentFamilyId' => '<string>',
'fileIndex' => 123,
'fileName' => '<string>'
]
]
],
'deletes' => [
'documentFamilyIds' => [
'<string>'
]
],
'documentFamilyIds' => [
'<string>'
],
'labelUpdates' => [
'newLabels' => [
[
]
],
'removedLabels' => [
[
]
]
],
'projectId' => '<string>',
'task' => [
],
'userWorkSession' => [
'activeDurationMs' => 123,
'clientNow' => '2023-11-07T05:31:56Z',
'elapsedMs' => 123,
'startedAt' => '2023-11-07T05:31:56Z'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://platform.kodexa.ai/api/batch-update"
payload := strings.NewReader("{\n \"contentObjectUploads\": {\n \"uploads\": [\n {\n \"documentFamilyId\": \"<string>\",\n \"fileIndex\": 123,\n \"fileName\": \"<string>\"\n }\n ]\n },\n \"deletes\": {\n \"documentFamilyIds\": [\n \"<string>\"\n ]\n },\n \"documentFamilyIds\": [\n \"<string>\"\n ],\n \"labelUpdates\": {\n \"newLabels\": [\n {}\n ],\n \"removedLabels\": [\n {}\n ]\n },\n \"projectId\": \"<string>\",\n \"task\": {},\n \"userWorkSession\": {\n \"activeDurationMs\": 123,\n \"clientNow\": \"2023-11-07T05:31:56Z\",\n \"elapsedMs\": 123,\n \"startedAt\": \"2023-11-07T05:31:56Z\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://platform.kodexa.ai/api/batch-update")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"contentObjectUploads\": {\n \"uploads\": [\n {\n \"documentFamilyId\": \"<string>\",\n \"fileIndex\": 123,\n \"fileName\": \"<string>\"\n }\n ]\n },\n \"deletes\": {\n \"documentFamilyIds\": [\n \"<string>\"\n ]\n },\n \"documentFamilyIds\": [\n \"<string>\"\n ],\n \"labelUpdates\": {\n \"newLabels\": [\n {}\n ],\n \"removedLabels\": [\n {}\n ]\n },\n \"projectId\": \"<string>\",\n \"task\": {},\n \"userWorkSession\": {\n \"activeDurationMs\": 123,\n \"clientNow\": \"2023-11-07T05:31:56Z\",\n \"elapsedMs\": 123,\n \"startedAt\": \"2023-11-07T05:31:56Z\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://platform.kodexa.ai/api/batch-update")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"contentObjectUploads\": {\n \"uploads\": [\n {\n \"documentFamilyId\": \"<string>\",\n \"fileIndex\": 123,\n \"fileName\": \"<string>\"\n }\n ]\n },\n \"deletes\": {\n \"documentFamilyIds\": [\n \"<string>\"\n ]\n },\n \"documentFamilyIds\": [\n \"<string>\"\n ],\n \"labelUpdates\": {\n \"newLabels\": [\n {}\n ],\n \"removedLabels\": [\n {}\n ]\n },\n \"projectId\": \"<string>\",\n \"task\": {},\n \"userWorkSession\": {\n \"activeDurationMs\": 123,\n \"clientNow\": \"2023-11-07T05:31:56Z\",\n \"elapsedMs\": 123,\n \"startedAt\": \"2023-11-07T05:31:56Z\"\n }\n}"
response = http.request(request)
puts response.read_body{
"contentObjectUpdates": [
{
"changeSequence": 123,
"contentObject": {
"changeSequence": 123,
"id": "<string>"
},
"documentFamily": {},
"documentFamilyId": "<string>",
"error": "<string>",
"linkedDeltaId": "<string>",
"success": true
}
],
"task": {}
}Batch Updates
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.
POST
/
api
/
batch-update
Process batch document update
curl --request POST \
--url https://platform.kodexa.ai/api/batch-update \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"contentObjectUploads": {
"uploads": [
{
"documentFamilyId": "<string>",
"fileIndex": 123,
"fileName": "<string>"
}
]
},
"deletes": {
"documentFamilyIds": [
"<string>"
]
},
"documentFamilyIds": [
"<string>"
],
"labelUpdates": {
"newLabels": [
{}
],
"removedLabels": [
{}
]
},
"projectId": "<string>",
"task": {},
"userWorkSession": {
"activeDurationMs": 123,
"clientNow": "2023-11-07T05:31:56Z",
"elapsedMs": 123,
"startedAt": "2023-11-07T05:31:56Z"
}
}
'import requests
url = "https://platform.kodexa.ai/api/batch-update"
payload = {
"contentObjectUploads": { "uploads": [
{
"documentFamilyId": "<string>",
"fileIndex": 123,
"fileName": "<string>"
}
] },
"deletes": { "documentFamilyIds": ["<string>"] },
"documentFamilyIds": ["<string>"],
"labelUpdates": {
"newLabels": [{}],
"removedLabels": [{}]
},
"projectId": "<string>",
"task": {},
"userWorkSession": {
"activeDurationMs": 123,
"clientNow": "2023-11-07T05:31:56Z",
"elapsedMs": 123,
"startedAt": "2023-11-07T05:31:56Z"
}
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
contentObjectUploads: {
uploads: [{documentFamilyId: '<string>', fileIndex: 123, fileName: '<string>'}]
},
deletes: {documentFamilyIds: ['<string>']},
documentFamilyIds: ['<string>'],
labelUpdates: {newLabels: [{}], removedLabels: [{}]},
projectId: '<string>',
task: {},
userWorkSession: {
activeDurationMs: 123,
clientNow: '2023-11-07T05:31:56Z',
elapsedMs: 123,
startedAt: '2023-11-07T05:31:56Z'
}
})
};
fetch('https://platform.kodexa.ai/api/batch-update', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://platform.kodexa.ai/api/batch-update",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'contentObjectUploads' => [
'uploads' => [
[
'documentFamilyId' => '<string>',
'fileIndex' => 123,
'fileName' => '<string>'
]
]
],
'deletes' => [
'documentFamilyIds' => [
'<string>'
]
],
'documentFamilyIds' => [
'<string>'
],
'labelUpdates' => [
'newLabels' => [
[
]
],
'removedLabels' => [
[
]
]
],
'projectId' => '<string>',
'task' => [
],
'userWorkSession' => [
'activeDurationMs' => 123,
'clientNow' => '2023-11-07T05:31:56Z',
'elapsedMs' => 123,
'startedAt' => '2023-11-07T05:31:56Z'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://platform.kodexa.ai/api/batch-update"
payload := strings.NewReader("{\n \"contentObjectUploads\": {\n \"uploads\": [\n {\n \"documentFamilyId\": \"<string>\",\n \"fileIndex\": 123,\n \"fileName\": \"<string>\"\n }\n ]\n },\n \"deletes\": {\n \"documentFamilyIds\": [\n \"<string>\"\n ]\n },\n \"documentFamilyIds\": [\n \"<string>\"\n ],\n \"labelUpdates\": {\n \"newLabels\": [\n {}\n ],\n \"removedLabels\": [\n {}\n ]\n },\n \"projectId\": \"<string>\",\n \"task\": {},\n \"userWorkSession\": {\n \"activeDurationMs\": 123,\n \"clientNow\": \"2023-11-07T05:31:56Z\",\n \"elapsedMs\": 123,\n \"startedAt\": \"2023-11-07T05:31:56Z\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://platform.kodexa.ai/api/batch-update")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"contentObjectUploads\": {\n \"uploads\": [\n {\n \"documentFamilyId\": \"<string>\",\n \"fileIndex\": 123,\n \"fileName\": \"<string>\"\n }\n ]\n },\n \"deletes\": {\n \"documentFamilyIds\": [\n \"<string>\"\n ]\n },\n \"documentFamilyIds\": [\n \"<string>\"\n ],\n \"labelUpdates\": {\n \"newLabels\": [\n {}\n ],\n \"removedLabels\": [\n {}\n ]\n },\n \"projectId\": \"<string>\",\n \"task\": {},\n \"userWorkSession\": {\n \"activeDurationMs\": 123,\n \"clientNow\": \"2023-11-07T05:31:56Z\",\n \"elapsedMs\": 123,\n \"startedAt\": \"2023-11-07T05:31:56Z\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://platform.kodexa.ai/api/batch-update")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"contentObjectUploads\": {\n \"uploads\": [\n {\n \"documentFamilyId\": \"<string>\",\n \"fileIndex\": 123,\n \"fileName\": \"<string>\"\n }\n ]\n },\n \"deletes\": {\n \"documentFamilyIds\": [\n \"<string>\"\n ]\n },\n \"documentFamilyIds\": [\n \"<string>\"\n ],\n \"labelUpdates\": {\n \"newLabels\": [\n {}\n ],\n \"removedLabels\": [\n {}\n ]\n },\n \"projectId\": \"<string>\",\n \"task\": {},\n \"userWorkSession\": {\n \"activeDurationMs\": 123,\n \"clientNow\": \"2023-11-07T05:31:56Z\",\n \"elapsedMs\": 123,\n \"startedAt\": \"2023-11-07T05:31:56Z\"\n }\n}"
response = http.request(request)
puts response.read_body{
"contentObjectUpdates": [
{
"changeSequence": 123,
"contentObject": {
"changeSequence": 123,
"id": "<string>"
},
"documentFamily": {},
"documentFamilyId": "<string>",
"error": "<string>",
"linkedDeltaId": "<string>",
"success": true
}
],
"task": {}
}Task status in the response
Send the task’s status asstatusSlug 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.
{
"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 typeDONE, 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):
{
"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."
}
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.
409 Conflict for a stale changeSequence on the task; the two cases share the CONFLICT code and are distinguished by the message.Authorizations
x-api-keybearerAuth
API key for authentication. Create one from the Kodexa platform UI under Settings > Access Tokens.
Body
application/jsonmultipart/form-data
A batch update request containing multiple document operations to be processed atomically.
Content object file uploads to add to document families.
Show child attributes
Show child attributes
Document families to delete.
Show child attributes
Show child attributes
IDs of document families to include in the batch.
Label additions and removals.
Show child attributes
Show child attributes
ID of the project containing the document families.
Optional task data to associate with the batch update.
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.
Show child attributes
Show child attributes