Update Entities

How to update entities using Compare-And-Swap (CAS) for safe concurrent updates.

Basic Update

PUT /entities/:id
Content-Type: application/json
Authorization: Bearer <token>

{
  "expected_cid": "bafyreig...",
  "properties_merge": {
    "description": "Updated description"
  }
}

CAS Requirement

The expected_cid field is required. It must match the entity's current tip CID. If another update occurred since you last read the entity, you'll get a 409 Conflict error.

Recovery pattern:

Fetch the entity again to get the new CID
Reapply your changes
Retry the update with the new CID

Update Fields

Field	Description
`expected_cid`	Required. Current tip CID for CAS guard.
`properties_merge`	Merge into existing properties (shallow merge)
`properties_replace`	Replace all properties entirely
`relationships_add`	Add new relationships
`relationships_remove`	Remove relationships by predicate + peer
`note`	Version note for this update

Adding Relationships

{
  "expected_cid": "bafyreig...",
  "relationships_add": [
    {
      "predicate": "references",
      "peer": "01JOTHER..."
    }
  ]
}

Removing Relationships

{
  "expected_cid": "bafyreig...",
  "relationships_remove": [
    {
      "predicate": "references",
      "peer": "01JOTHER..."
    }
  ]
}

Conflict Resolution

When you receive a 409 Conflict:

{
  "error": "CAS conflict",
  "expected": "bafyreig...",
  "actual": "bafyreih...",
  "status": 409
}

The actual field contains the current tip CID. Fetch the latest version, merge your changes, and retry.