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": {}
}

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

{
  "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):

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

Authorizations

x-api-key

string

header

required

API key for authentication. Create one from the Kodexa platform UI under Settings > Access Tokens.

Body

A batch update request containing multiple document operations to be processed atomically.

contentObjectUploads

object

Content object file uploads to add to document families.

Show child attributes

deletes

object

Document families to delete.

Show child attributes

documentFamilyIds

string[]

IDs of document families to include in the batch.

labelUpdates

object

Label additions and removals.

Show child attributes

projectId

string

ID of the project containing the document families.

task

object

Optional task data to associate with the batch update.

userWorkSession

object

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

Response

Batch update result

Response from a batch update operation, containing results for each document family.

contentObjectUpdates

object[]

Results for each content object upload.

Show child attributes

task

object

Updated task data, if a task was included in the batch.