update

Rewrite one existing fact in place.

POST/v1/update

Also an MCP tool named update.

Find the fact with recall first. Every fact in a response has a ref, the last 5 characters of its id. Pass the fact's subject, predicate, and ref, plus what should change.

Field	Type	Required	Description
`subject`	string	yes	Current subject, exactly as stored.
`predicate`	string	yes	Current predicate. `WorksAt` finds `works_at`.
`ref`	string	yes	Last 5 characters of the fact id, or the full id.
`new_subject`	string	no	Replacement subject. Max 45 characters. Links to that exact entity name.
`new_predicate`	string	no	Replacement predicate.
`new_object`	string \| JSON	no	Replacement object: text, a `type:id`, or JSON.
`context`	string	no	Replacement note. Max 4000 characters.
`if_object`	string \| JSON	no	Apply the update only while the stored object still equals this value. JSON is compared by content. Use it for counters and anything two writers may change at once.
`collection`	string	no	Collection code. Omit for the connection default. `""` forces the default bucket.

Set at least one of new_subject, new_predicate, new_object, or context. Omitted fields keep their stored values.

Request

{
  "subject": "task:GO-12",
  "predicate": "status",
  "ref": "X2C9A",
  "new_object": "done",
  "if_object": "in_progress"
}

Response

{
  "before": { "id": "01KJ8Z3W5Q2YB7N4R6T8VX2C9A", "ref": "X2C9A", "subject": "task:GO-12", "predicate": "status", "value": "in_progress" },
  "after":  { "id": "01KJ8Z3W5Q2YB7N4R6T8VX2C9A", "ref": "X2C9A", "subject": "task:GO-12", "predicate": "status", "value": "done" }
}

Errors

| Status | When | |:--|:--| | 400 | No change requested, or ref is not 5 or 26 id characters | | 404 | No fact matches subject, predicate, and ref | | 409 | Two facts share the ref; pass the full id as ref | | 409 | if_object no longer matches: fact changed: current object is …. Recall and retry |

To set a single-value predicate without reading first, use remember with replace: true.