Batch Operations and Versioning

Versioning

The API has no global version prefix: paths such as /documents and /projects are unversioned. Versioning is per endpoint. Where an endpoint's response contract changed, the new contract ships at a new path ending in /v2, and the original path keeps its original behavior. Today that applies to the batch mutation endpoints.

How v1 and v2 differ

POST /documents/batch-update-status (v1) refuses the whole batch on the first problem it finds, such as a missing id or a status the document's type cannot hold. Its /v2 counterpart takes the same request body, applies the items it can, and reports the rest item by item.

The v2 response

When the request itself is accepted, a /v2 batch endpoint answers 200 with a BatchMutationResponse under data, even if some items failed. Read each item's result; do not treat the response status as the outcome of every item.

{
  "success": true,
  "data": {
    "transactionId": "3f0c2a8e-5d1b-4c6e-9a7f-2b8d4e1f0a93",
    "results": [
      { "id": "550e8400-e29b-41d4-a716-446655440000", "status": 200 },
      {
        "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "status": 409,
        "code": "stale_status",
        "message": "..."
      }
    ]
  }
}

• results holds one entry per distinct requested id, in the order you first named it.
• An entry with status: 200 was applied. It may carry an operation-specific outcome; batch tag removal reports removed or not_present.
• Any other status is a failure of that item alone, and always carries code and message. The statuses are 400 (not satisfiable for this item), 404 (not found in your organization), 409 (a stale precondition), 424 (not applied because another item in the batch failed), and 500 (the server could not confirm the outcome).
• transactionId is optional and omitted when absent. It identifies the group of records the mutation wrote.

The set of failure codes is open: treat a code you do not recognize as a generic item failure.

Request-level problems, such as a malformed body or a missing scope, still return the ordinary error envelope with a 4xx status, as described in Responses and errors.

Choosing the items

The document batch endpoints take either documentIds, a list of up to 500 UUIDs, or selection, a query the server resolves inside the mutation. Send exactly one. A selection that resolves to more than 500 documents is refused with code: "selection_too_large", not truncated. selection.excludedIds can narrow the resolved set but never widen it. Each endpoint page has the full body schema.