Bulk upsert entities by ID
Accepts an array of entities. For each: creates it if it does not exist, then writes ValueDiffs only for keys whose values have changed. Optionally links each entity as a downstream child of a parent. New children append in input order, including across successive requests. All diffs are written in a single DB round-trip for efficiency. Concurrent upserts matching the same external identifier (idField) are serialized server-side, so they converge on one entity instead of creating duplicates. Parents and children may be created atomically in one batch when parentIds contains Flow entity UUIDs, including UUIDs assigned to parent rows in that batch. parentIds does not resolve idField aliases; resolve or create such a parent first if its Flow UUID is unknown. The operation is atomic and safe to retry with the same stable IDs. If Claude Desktop reports “No result received … after waiting 4 minutes”, first read those IDs because the approval/dispatch may have been lost before Flow received the call; never replace the IDs merely because the result was lost. Field definition validation is intentionally skipped — callers may write arbitrary key names without pre-defining them in the schema.
Authorizations
Headers
Workspace identifier
Path Parameters
Query Parameters
Whether newly inserted entities in the upsert batch are assigned to the authenticated user. Defaults to true; existing entities are unaffected.
Branch to write all entities to. Omit or pass "master" for the base branch.
Body
Entity type (e.g. "task", "bug"). Must match an existing type in the schema.
Entity ID (UUID). Must be unique within the project.
Key-value pairs to compare and write. Only keys whose values differ from the stored state will produce diffs.
Optional field key to match id against instead of treating id as the Flow entity id. When set, id is interpreted as an external identifier and matched against the current value of this field across existing entities on the branch: a match reuses that entity, a miss creates a new one with a freshly generated Flow id. This decouples the Flow entity id from any one external field (e.g. match on a custom "ReqIF ID" field). Omit (or leave the field empty) to keep the default behaviour where id is the Flow entity id verbatim.
Optional list of parent entity IDs. For each parent, a downstream link is created from that parent to this entity if one does not already exist. Existing upstream links that are not listed here are left untouched.